---
name: Prepare your machine
summary: Supporting material for installing git, Node, and the IdeaSpaces plugin — written to be handed to your local agent (Claude or Codex), which either does the setup itself or guides you through it one command at a time. You do not need to follow these steps yourself.
---

# 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](../explore/what-is-git.md). 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:

1. **git** — keeps a history of their files.
2. **Node.js v20 or newer** — runs the plugin's tooling.
3. **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):

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

**Windows** (PowerShell):

```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](https://nodejs.org/en/download); 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](https://git-scm.com/download/win) (accept defaults), Node LTS from [nodejs.org](https://nodejs.org/en/download). |
| 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](https://github.com/IdeaSpaces-xyz/pi-is-space).

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."

## Next

Return to [the manual](../README.md), 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.