Prepare Your Machine

You do not need to read this page. Hand it to your agent.

If you are reading this as a person: open your local agent — Claude or Codex — point it at this page (paste the text or the link), and say:

"Help me get my machine ready using this page."

If you are curious why Git is needed, read how Git remembers changes. The rest of this page is written for the agent.

For the agent

Goal

This person's machine needs three things, all usable from the agent app they will work in:

git — keeps a history of their files.
Node.js v20 or newer — runs the plugin's tooling.
The ideaspaces plugin, installed and enabled.

Get the machine to that state and prove it with the checks below. The person may never have used a terminal: explain each step in a sentence, one step at a time, and do not move on until the current step is confirmed.

Two ways to work

If you can run commands on this person's computer, do so and show them what happened.

If you cannot — you run in a cloud sandbox, a web chat, or anywhere that is not their machine — guide them instead. Tell them how to open a terminal (macOS: ⌘ Space, type Terminal, Return. Windows: Start key, type PowerShell, Enter. Linux: Ctrl+Alt+T), give them one command at a time, and ask them to paste back what it printed.

Everywhere below, "run" means whichever of these applies. Commands you run in a sandbox tell you nothing about their machine.

First establish the operating system: run uname -s (Darwin = macOS, Linux = Linux, an error = Windows), or simply ask.

Fast path — the setup script

One command checks the machine, installs only what is missing, and ends with a short report. It is safe to run again.

macOS and Linux (Terminal):

curl -fsSL https://ideaspaces.xyz/setup.sh | bash

Windows (PowerShell):

irm https://ideaspaces.xyz/setup.ps1 | iex

To only check, without changing anything: curl -fsSL https://ideaspaces.xyz/setup.sh | bash -s -- --check on macOS and Linux, or & ([scriptblock]::Create((irm https://ideaspaces.xyz/setup.ps1))) -Check on Windows.

The report ends with two lines to act on:

result: ready | action needed | failed
next:   <what to do now, in plain words>

ready — go to Restart the agent app.
action needed — the person has to do one thing the script cannot: click through an installer window, or type their password. Relay the next: line in your own words, wait until they say it is done, then run the script again. Repeat until ready.
failed — read the next: line and the output above it; use Known traps and Manual install below.

When you run the script yourself, an installer window or password prompt appears on the person's screen, not in your output — tell them to look for it.

Check

The script's report covers this. Without the script:

git --version
node --version
npm --version

The machine is ready for the plugin when git prints a version, Node prints v20 or higher, and npm prints a version. Install only what fails.

Manual install

Use this when the script cannot run or keeps failing. Some paths ask for the person's computer password — tell them before it appears, and never ask them to type it to you.

	git	Node (current LTS)
macOS	`xcode-select --install`, then click Install in the window that opens. `brew install git` if Homebrew is already there.	The LTS `.pkg` installer from nodejs.org; asks for the Mac password. `brew install node` if Homebrew is already there.
Windows	`winget install --id Git.Git -e`	`winget install --id OpenJS.NodeJS.LTS -e`
Linux	`sudo apt install git` or `sudo dnf install git`	nvm (below) — not the distribution's package.

Linux Node, via nvm (user-level, no password):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash

Then open a new terminal and run nvm install --lts.

After installing by hand, re-run the checks in a new terminal (or a new login shell, zsh -l / bash -l, if you run them yourself).

Restart the agent app

The agent app read the PATH when it started, so it does not see tools installed after that. If anything was installed, ask the person to fully quit and reopen the agent app (macOS: ⌘Q, not just closing the window).

Known traps

Read this when something does not go as expected.

What you see	What is going on	What to do
macOS: running `git` opens a window offering "command line developer tools"	git is missing; this window is the installer.	Have them click Install. Not an error.
macOS: the developer tools install seems stuck	It commonly takes 10–20 minutes.	Wait for the person to confirm it finished. Do not start another install.
`node` prints a version below v20	An old Node is installed.	Install the current LTS as above, then check in a new terminal. If the old version still answers, a second Node is earlier on the PATH — run `which -a node` (Windows: `where.exe node`) and show the person what you found before removing anything.
Linux: the package manager's Node is old	Many distributions ship old Node (Ubuntu 22.04: v12).	Use nvm.
Install succeeded but the command is still "not found"	The terminal was opened before the install and holds the old PATH.	Close the terminal, open a new one, check again.
Windows: `winget` is "not recognized"	Older Windows without winget.	Installers instead: git from git-scm.com (accept defaults), Node LTS from nodejs.org.
Windows: "Do you want to allow this app to make changes?"	Normal installer prompt.	Click Yes.
Windows: `npm --version` says "running scripts is disabled"	PowerShell blocks the `npm` shortcut script; Node itself is fine.	`npm.cmd --version` confirms it. Do not change the execution policy for them.
macOS: Node works in Terminal but the plugin cannot find it	Node was installed via nvm/fnm, which only the terminal sees — not a desktop app opened from the Dock.	Install the nodejs.org `.pkg` as well.
Plugin installed but not working	The agent app has not been restarted since Node or the plugin was installed.	Fully quit and reopen the app.
The same step fails twice	Something unusual about this machine.	Stop. Tell the person exactly what you saw; do not improvise other installers.

Install the plugin

The plugin comes from the GitHub marketplace IdeaSpaces-xyz/claude-code-plugin. Use the path for the app the person uses:

Claude Code in a terminal — inside a session:

/plugin marketplace add IdeaSpaces-xyz/claude-code-plugin
/plugin install ideaspaces@ideaspaces-xyz

Claude desktop app — Customize → Plugins → Add marketplace, paste IdeaSpaces-xyz/claude-code-plugin, then install ideaspaces from the list.

Codex — in a terminal:

codex plugin marketplace add IdeaSpaces-xyz/claude-code-plugin
codex plugin add ideaspaces@ideaspaces-xyz

Pi — follow IdeaSpaces for Pi.

Then fully quit and reopen the agent app so the plugin loads.

Done when

The three checks pass in a new terminal, with Node v20 or higher.
The agent app was restarted after the last install.
ideaspaces shows as installed and enabled in the app's plugin list.

Only then tell the person: "Your machine is ready."

Return to the manual, give its public address to your agent, and say:

Bring home a copy of the Explorers' Manual from https://ideaspaces.xyz/repos/n_ba793faed9389f32f7f59828 and show me where to begin.