From c97eeeee0b146d2065731973daddd5afbf0b655b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alejandro=20Guti=C3=A9rrez?= <35082514+alezmad@users.noreply.github.com> Date: Sun, 5 Apr 2026 14:28:07 +0100 Subject: [PATCH] docs: 5-minute quickstart walkthrough for v0.1.0 launch --- docs/QUICKSTART.md | 221 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 221 insertions(+) create mode 100644 docs/QUICKSTART.md diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md new file mode 100644 index 0000000..8ae12e2 --- /dev/null +++ b/docs/QUICKSTART.md @@ -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/ + ``` + +--- + +## 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.*