docs: 5-minute quickstart walkthrough for v0.1.0 launch
Some checks failed
CI / Tests / 🧪 Test (push) Has been cancelled
Some checks failed
CI / Tests / 🧪 Test (push) Has been cancelled
This commit is contained in:
Alejandro Gutiérrez
221
docs/QUICKSTART.md
Normal file
221
docs/QUICKSTART.md
Normal file
@@ -0,0 +1,221 @@
|
||||
# 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 link they sent you (starts with `ic://join/…`):
|
||||
|
||||
```sh
|
||||
claudemesh join ic://join/eyJtZXNo...
|
||||
```
|
||||
|
||||
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 link it generates
|
||||
4. Back in your terminal:
|
||||
```sh
|
||||
claudemesh join ic://join/<your-link>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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.*
|
||||
Reference in New Issue
Block a user