# Feeling stuck setting up MeshCode? Paste this into any AI.

Hey AI (Claude, ChatGPT, Cursor, whoever). The human you're talking to is trying to set up **MeshCode** and wants you to walk them through it step by step. Read this whole file first, then go one step at a time, waiting for confirmation between each.

---

## What is MeshCode?

MeshCode is a **command-line tool** (CLI) for macOS / Linux / Windows that launches **Claude Code** (Anthropic's terminal app) with a pre-wired team of persistent AI agents that can talk to each other, remember things, and run in parallel.

It is **not** a normal MCP server you add to your existing Claude. It's a CLI that **launches** Claude Code with the meshwork already plugged in.

The three commands the user needs to run are:

```bash
pip install meshcode          # installs the Python CLI
meshcode init                 # signs them in (browser opens for OAuth, or paste an API key)
meshcode go my-agent          # launches Claude Code with MeshCode wired up
```

---

## Your job

Walk the user from "nothing installed" to "agents running" without skipping steps. Do **not** assume they have Python, pip, Claude Code, or PATH set up — many MeshCode users are non-developers.

Go step by step:

### Step 1 — Identify their OS

Ask: "Are you on macOS, Windows, or Linux?"

### Step 2 — Check Python

Ask them to open a terminal:
- macOS: `Cmd+Space`, type `Terminal`, Enter.
- Windows: `Win+R`, type `powershell`, Enter.
- Linux: probably already in one.

Have them run:

```bash
python3 --version
```

If it prints a version like `Python 3.12.5`, they're good. If it says "command not found":
- macOS: tell them to install Python 3 from <https://www.python.org/downloads/macos/> (download the universal2 .pkg, double-click, defaults are correct). Then run `/Applications/Python\ 3.x/Install\ Certificates.command`.
- Windows: install from <https://www.python.org/downloads/windows/> — IMPORTANT: check "Add Python to PATH" on the first installer screen.
- Linux: `sudo apt install python3 python3-pip` (or distro equivalent).

### Step 3 — Install MeshCode

```bash
pip install --user meshcode
```

If "pip: command not found":
- macOS: add Python's user bin to PATH — run `echo 'export PATH="$HOME/Library/Python/$(python3 -c "import sys;print(f\"{sys.version_info.major}.{sys.version_info.minor}\")")/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc` and try again.
- Windows: use `python -m pip install meshcode --user` instead.
- Linux: try `python3 -m pip install --user meshcode`.

Verify with `meshcode --version`. If you see a version number, you're done with this step.

### Step 4 — Install Claude Code

MeshCode launches Claude Code, so Claude Code must be installed:

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

(macOS / Linux. On Windows, follow Anthropic's official Windows install at <https://claude.ai/download>.)

Verify with `claude --version`.

### Step 5 — Authenticate

```bash
meshcode init
```

This will either open a browser (device-code OAuth, recommended) or ask for an API key. If they need an API key, send them to <https://meshcode.io/account/keys> to create one.

**SECURITY:** they should paste the key directly into the terminal prompt — **never** into a chat with you or another AI, never into Slack, email, or screenshots. If they already did, tell them to rotate immediately: <https://meshcode.io/docs/security/rotate-key>.

### Step 6 — Create their first agent

```bash
meshcode setup my-project my-agent
```

This registers `my-agent` in a fresh meshwork called `my-project`.

### Step 7 — Launch

```bash
meshcode go my-agent
```

Claude Code opens with MeshCode pre-wired. Inside the chat, they can say things like "send a hello to mesh-commander" and watch other agents respond.

---

## Common errors and what to do

- **`SSL: CERTIFICATE_VERIFY_FAILED`** — macOS only, after python.org install. Run `/Applications/Python\ 3.x/Install\ Certificates.command` once.
- **`command not found: meshcode`** — PATH issue. Open a fresh terminal and retry. If still failing on macOS, redo the `~/.zshrc` PATH export from Step 3.
- **`command not found: claude`** — fresh terminal usually fixes it. If not, the Anthropic install didn't finish; rerun the curl one-liner.
- **`pip install` hangs** — they're behind a corporate proxy or have a flaky network. Try `pip install --user --no-cache-dir -i https://pypi.org/simple/ meshcode`.
- **They pasted an API key into a chat by accident** — go straight to <https://meshcode.io/docs/security/rotate-key>. It takes 30 seconds and invalidates the old key immediately.

---

## When in doubt

Point them at the official walkthrough: <https://meshcode.io/docs/install/macos>.

Or the troubleshooting catalog: <https://meshcode.io/docs/troubleshooting>.

That's it. Go one step at a time. Don't assume; verify each step before moving on.