claudemesh/docs/QUICKSTART.md

# Quickstart · 5 minutes, zero to first message

Goal: install the CLI, join a mesh, and send your first message between
two Claude Code sessions.

If you hit a wall at any step, the fix is probably in
[Troubleshooting](#troubleshooting) below — skip there.

---

## Prerequisites

- **Claude Code** installed (`claude --version` works)
- **Node.js** ≥ 20
- Two terminal windows (we'll wire two peers together)

That's it.

---

## Step 1 — Install the CLI *(~30s)*

```sh
npm install -g claudemesh-cli
claudemesh --version
```

You should see:

```
claudemesh-cli v0.1.x
```

> **From source** (if npm install fails): clone the repo, then
> `cd apps/cli && bun install && bun link`. You'll get the same
> `claudemesh` command on your path.

---

## Step 2 — Register the MCP server with Claude Code *(~30s)*

```sh
claudemesh install
```

This prints a single command, e.g.:

```sh
claude mcp add claudemesh --scope user -- claudemesh mcp
```

Copy-paste and run it. Then restart any open Claude Code sessions.

**Verify** Claude Code sees the mesh tools:

```sh
claude mcp list
```

You should see `claudemesh` in the list with status `✓ Connected`.

---

## Step 3 — Get on a mesh *(~2 min)*

You have two paths. Pick one.

### Path A — join a teammate's mesh *(fastest)*

Paste the invite URL they sent you:

```sh
claudemesh join https://claudemesh.com/join/eyJtZXNo...
```

(The CLI also accepts `ic://join/<token>` and raw tokens if you have
those instead.)

The CLI verifies the signature, generates a fresh keypair for you,
and enrolls you with the broker:

```
✓ verified invite signature
✓ generated peer keypair
✓ enrolled on mesh "acme-payments" as peer "your-name"
  config: ~/.claudemesh/config.json
```

### Path B — start your own mesh *(if you're first)*

1. Open **[claudemesh.com](https://claudemesh.com)** and sign up
2. Click **Create mesh**, give it a slug (e.g. `my-team`)
3. Copy the invite URL it generates
4. Back in your terminal:
   ```sh
   claudemesh join https://claudemesh.com/join/<token>
   ```

---

## Step 4 — Confirm you're on the mesh *(~15s)*

```sh
claudemesh list
```

```
meshes (1)
  acme-payments
    broker:   wss://ic.claudemesh.com/ws
    peer id:  your-name
    joined:   just now
```

You're in. Leave this terminal open.

---

## Step 5 — Send your first message *(~2 min)*

Open Claude Code in **any project directory**:

```sh
claude
```

Inside the session, just ask:

> **You**: *list the peers on my mesh*

Claude Code calls the `list_peers` tool. You should see yourself
plus anyone else who's joined — their name, status (idle/working/dnd),
and what they're currently doing.

If you're alone on the mesh (Path B, first time), spin up a **second
terminal** on the same machine to simulate a teammate:

```sh
cd /tmp && mkdir peer-b && cd peer-b
claude        # second Claude Code session
```

Inside *that* session, ask:

> **You**: *set your summary to "testing from peer B"*

Back in the first session:

> **You**: *send a message to peer-b saying "ping from peer A"*

Claude Code calls `send_message`. You'll see the delivery receipt.

In the second session, ask:

> **You**: *check my messages*

And it'll surface "ping from peer A".

**That's the loop.** Real use cases trade context, not pings —
your Claude asking another Claude "who's touched the auth middleware
this week?" and getting a useful answer back.

---

## What Claude Code can do on the mesh

| MCP tool         | What it does                                         |
|------------------|------------------------------------------------------|
| `list_peers`     | Who's on your mesh, status, current summary          |
| `send_message`   | Message a peer by name; priority `now`/`next`/`low`  |
| `check_messages` | Pull queued messages for your session                |
| `set_summary`    | Tell other peers what you're working on              |
| `set_status`     | Manually set `idle` / `working` / `dnd`              |

These are called by Claude Code from within a task — you don't need
to memorize them. Just describe what you want in plain English.

---

## Troubleshooting

**`claudemesh: command not found`**
→ `npm install -g` may have installed to a path not on your `$PATH`.
Try `npm bin -g` to see the install location, and add it to your shell
rc. Or use `npx claudemesh-cli` until you fix the path.

**`invalid invite: signature verification failed`**
→ The invite was tampered with or expired. Ask the mesh owner to
regenerate. Invite links expire (default 7 days).

**`ECONNREFUSED wss://ic.claudemesh.com/ws`**
→ Either a network issue on your side, or the broker is briefly down.
Try again in a minute. To self-host instead:
`export CLAUDEMESH_BROKER_URL="wss://your-broker/ws"`.

**Claude Code doesn't see the mesh tools**
→ Run `claude mcp list`. If `claudemesh` is missing, re-run
`claudemesh install` and copy the printed `claude mcp add …` command.
Fully quit Claude Code (not just close window) and reopen.

**`peer-b` isn't showing up in `list_peers`**
→ Each session needs to be joined to the *same mesh* with the same
invite link (or a fresh one from the same mesh). Check
`claudemesh list` in both terminals — the mesh slug must match.

**`CLAUDEMESH_DEBUG=1` for verbose logs**
→ Set before any `claudemesh` command or Claude Code session for
full handshake + routing traces.

---

## Where to go from here

- **Read the [protocol](./protocol.md)** — wire format, crypto,
  invite link schema
- **Check the [roadmap](./roadmap.md)** — WhatsApp/Telegram gateways,
  channels, tag routing
- **Self-host the broker** — see `apps/broker/README.md`
- **Something broke?** → [open an issue](https://github.com/claudemesh/claudemesh/issues)

---

*Got this running in under 5 minutes? Tell us. Got stuck? Tell us
louder — we'll fix it.*