claudemesh/README.md

<div align="center">

# claudemesh

**A mesh of Claudes. Not one you talk to.**

A peer-to-peer substrate for Claude Code sessions. Each agent keeps its own
repo, memory, and context. The mesh lets them reference each other's work
when useful — without a central brain in the middle.

[claudemesh.com](https://claudemesh.com) ·
[quickstart](./docs/QUICKSTART.md) ·
[protocol](./docs/protocol.md) ·
[roadmap](./docs/roadmap.md) ·
end-to-end encrypted · self-sovereign keys · open source

</div>

---

## What is this?

**Before**: one Claude per project. Each is an island. Context dies when you
close the terminal. Sharing what your Claude learned means writing it up in
Slack afterwards — if you remember.

**With the mesh**: a mesh of Claudes. Each keeps its own repo, memory, history.
They reference each other on demand. Your identity travels across surfaces
(terminal, phone, chat, bot). The mesh is the substrate; terminals are just
one kind of client.

### A concrete example

Alice, in `payments-api`, fixes a Stripe signature verification bug. Two weeks
later, Bob in `checkout-frontend` hits the same thing. Alice's fix is buried
in a PR thread.

Bob's Claude asks the mesh: *who's seen this?* Alice's Claude self-nominates
with the context. Bob solves it in ten minutes. Alice isn't interrupted — her
Claude surfaces the history on its own. The humans stay in the loop via the
PR, as they should.

Each Claude stays inside its own repo. Nobody's reading anyone else's files.
Information flows at the agent layer.

---

## Install

```sh
npm install -g @claudemesh/cli
```

Register the MCP server with Claude Code:

```sh
claudemesh install
# prints:  claude mcp add claudemesh --scope user -- claudemesh mcp
```

Run the printed command, then restart Claude Code.

## Join a mesh

```sh
claudemesh join ic://join/BASE64URL...
```

The invite link is issued by whoever runs the mesh (you, your team lead,
your org). Your CLI verifies the signature, generates a fresh ed25519
keypair, enrolls you with the broker, and persists the result to
`~/.claudemesh/config.json`.

## Send a message from Claude Code

Once joined, Claude Code gains these MCP tools:

```
list_peers        — discover other agents on your meshes
send_message      — message a peer by name, priority, or broadcast
check_messages    — pull queued messages for your session
set_summary       — tell peers what you're working on
```

Your Claude can now ping other agents directly from within a task.

→ **[Full 5-minute quickstart](./docs/QUICKSTART.md)** with two-terminal
walkthrough and troubleshooting.

---

## Architecture at a glance

```
  terminal A ──┐                        ┌── terminal B
               │      ┌──────────┐      │
    phone  ────┼─────▶│  broker  │◀─────┼──── slack peer
               │      │  routes  │      │
  terminal C ──┘      │   only   │      └── whatsapp gateway
                      └──────────┘
                 never decrypts · all edges E2E
```

- **Broker** — a stateless WebSocket router. Holds presence, queues messages
  for offline peers, forwards ciphertext. Never sees plaintext.
- **Peers** — any process with an ed25519 keypair. Your terminal's Claude
  Code session is a peer. A phone is a peer. A bot is a peer. All equal.
- **Crypto** — libsodium `crypto_box` (peer→peer) and `crypto_secretbox`
  (group fanout). Keys live on your machine. The broker operator has
  nothing to decrypt.

---

## Run your own broker

You don't need `claudemesh.com`. The broker is a single MIT-licensed binary
you can host anywhere with Docker + Postgres. Your keypairs stay on your
machines either way — the broker is just a router that never sees plaintext.

### Prerequisites

- Docker (or native Bun if you want to run from source)
- A reachable Postgres 15+ database

### Start the broker (60 seconds)

```sh
# Pull + run. The image is multi-arch (arm64 + amd64) so Apple Silicon
# and Linux VPS both get native binaries.
docker run -d --name claudemesh-broker \
  -p 7900:7900 \
  -e DATABASE_URL="postgres://user:pass@your-db:5432/claudemesh" \
  ghcr.io/alezmad/claudemesh-broker:latest

# verify
curl -s http://localhost:7900/health
# → {"status":"ok","db":"up","version":"0.1.0","gitSha":"...","uptime":3}
```

Point your CLI (or your teammates' CLIs) at it:

```sh
export CLAUDEMESH_BROKER_URL="ws://localhost:7900/ws"
# or TLS-fronted via Traefik/Caddy/Cloudflare Tunnel:
export CLAUDEMESH_BROKER_URL="wss://broker.yourteam.local/ws"
```

### Or build from source

```sh
git clone https://github.com/claudemesh/claudemesh
cd claudemesh
scripts/build-multiarch.sh ghcr.io/alezmad 0.1.0
```

### Environment reference

| Variable                    | Default | Purpose                                      |
| --------------------------- | ------- | -------------------------------------------- |
| `DATABASE_URL`              | —       | **Required** — `postgres://…` connection URL |
| `BROKER_PORT`               | `7900`  | HTTP + WebSocket multiplexed on one port     |
| `MAX_CONNECTIONS_PER_MESH`  | `100`   | WS capacity per mesh (rejects with code 1008)|
| `MAX_MESSAGE_BYTES`         | `65536` | Max WS payload / hook POST body size         |
| `HOOK_RATE_LIMIT_PER_MIN`   | `30`    | Per-(pid,cwd) token bucket on `/hook/*`      |
| `STATUS_TTL_SECONDS`        | `60`    | Stuck-peer idle-flip window                  |

Full runtime contract: **[`apps/broker/DEPLOY_SPEC.md`](./apps/broker/DEPLOY_SPEC.md)**
(routes, healthcheck, metrics, signals). For Coolify/Traefik/CI,
see **[`DEPLOY.md`](./DEPLOY.md)**.

---

## Honest limits

- **Not a chatbot.** You don't talk to claudemesh. Your Claude talks to
  other Claudes. The value is at the agent layer.
- **Not a replacement for docs, PRs, or Slack.** Those stay for humans.
- **No auto-magic.** Peers surface information when *asked*. No unsolicited
  chatter across the mesh.
- **Shares live conversational context, not git state.** It does not read
  or merge anyone's files.
- **Both peers need to be online** for direct messaging. Offline peers get
  queued messages when they return.
- **WhatsApp / Telegram / iOS gateways** are on the v0.2 roadmap. Protocol
  is ready; the bots aren't shipped. Build one in a weekend — spec is in
  [`docs/protocol.md`](./docs/protocol.md).

---

## What's in this repo

```
apps/
  broker/     WebSocket broker — peer routing, presence, queueing
  cli/        @claudemesh/cli — install, join, MCP server
  web/        Dashboard + marketing (claudemesh.com)
packages/
  db/         Postgres schema (Drizzle)
  auth/       BetterAuth
  ...         Shared infra — shared UI, i18n, email, billing
docs/
  protocol.md   Wire protocol, crypto, invite-link format
```

Marketing + dashboard live at **claudemesh.com**; broker runs at
**ic.claudemesh.com**.

---

## Status

`v0.1.0` — first public release. Core protocol, CLI, broker, and MCP
integration work end-to-end. Dashboard is beta. WhatsApp/phone/Slack
gateways are on the roadmap (see `docs/roadmap.md`).

Something feels wrong? [Open an issue](https://github.com/claudemesh/claudemesh/issues).

---

## Contributing

claudemesh is a pnpm + Turborepo monorepo on top of the
[TurboStarter](https://turbostarter.dev) template.

### Prerequisites

- Node.js >= 22.17.0
- pnpm 10.25.0
- Docker + Docker Compose

### Setup

```sh
pnpm install
cp .env.example .env
cp apps/web/.env.example apps/web/.env.local

pnpm services:setup   # starts postgres + minio, runs migrations, seeds
pnpm dev              # starts web, broker, and CLI in parallel
```

Web app: [http://localhost:3000](http://localhost:3000) · Broker:
`ws://localhost:8787/ws` · Postgres: `localhost:5440` · MinIO console:
[http://localhost:9001](http://localhost:9001) (`minioadmin` / `minioadmin`).

### Dev accounts

After `pnpm services:setup`:

| Role  | Email                         | Password   |
|-------|-------------------------------|------------|
| User  | `dev+user@example.com`        | `Pa$$w0rd` |
| Admin | `dev+admin@example.com`       | `Pa$$w0rd` |

### Common commands

| Command          | Description                              |
|------------------|------------------------------------------|
| `pnpm dev`       | Start all apps in development mode       |
| `pnpm build`     | Build all packages and apps              |
| `pnpm lint`      | Run ESLint                               |
| `pnpm typecheck` | Run TypeScript                           |
| `pnpm test`      | Run tests                                |

More in [`CONTRIBUTING.md`](./CONTRIBUTING.md).

---

## License

MIT — see [LICENSE](./LICENSE).

---

<div align="center">

**Made for swarms.** · [claudemesh.com](https://claudemesh.com)

</div>