alezmad/claudemesh
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(readme): rewrite for v0.1.0 public launch
Some checks failed
CI / Tests / 🧪 Test (push) Has been cancelled
Details

Browse Source 
Replaces the vanilla TurboStarter template with a claudemesh-first
README aligned to the landing page positioning.

- Lead with "mesh of Claudes, not one you talk to" mental shift
- Concrete use case (Alice/Bob Stripe bug) before any install steps
- Install + join flow with @claudemesh/cli
- ASCII architecture diagram: broker at center, peers orbiting
- Honest limits section (what it is NOT, what's roadmap)
- Repo layout section
- TurboStarter dev setup moved under Contributing
This commit is contained in:
Alejandro Gutiérrez
2026-04-05 14:19:05 +01:00
parent af35b19918
commit d1cab7b807
1 changed files with 192 additions and 168 deletions
Download Patch File Download Diff File Expand all files Collapse all files

360
README.md
View File

@@ -1,198 +1,222 @@
# TurboStarter Kit <div align="center">
Full-stack monorepo built with Next.js, Expo, Turborepo, and pnpm workspaces. # claudemesh
## Prerequisites **A mesh of Claudes. Not one you talk to.**
- [Node.js](https://nodejs.org/) >= 22.17.0 A peer-to-peer substrate for Claude Code sessions. Each agent keeps its own
- [pnpm](https://pnpm.io/) 10.25.0 repo, memory, and context. The mesh lets them reference each other's work
- [Docker](https://www.docker.com/) and Docker Compose when useful — without a central brain in the middle.
## Project Structure [claudemesh.com](https://claudemesh.com) ·
[docs](https://claudemesh.com/docs) ·
[protocol](./docs/protocol.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.
---
## 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.
Self-host the broker (`apps/broker`) and point your CLI at it:
```sh
export CLAUDEMESH_BROKER_URL="wss://broker.yourteam.local/ws"
```
---
## 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/ apps/
web/ # Next.js web application (port 3000) broker/ WebSocket broker — peer routing, presence, queueing
mobile/ # Expo React Native app cli/ @claudemesh/cli — install, join, MCP server
web/ Dashboard + marketing (claudemesh.com)
packages/ packages/
ai/ # AI provider integrations db/ Postgres schema (Drizzle)
analytics/ # Analytics providers auth/ BetterAuth
api/ # tRPC API layer ... Shared infra — shared UI, i18n, email, billing
auth/ # Authentication (BetterAuth) docs/
billing/ # Payment providers (Stripe, Lemon Squeezy, Polar) protocol.md Wire protocol, crypto, invite-link format
cms/ # Content management
db/ # Database (Drizzle ORM + PostgreSQL)
email/ # Email providers (Resend, Sendgrid, etc.)
i18n/ # Internationalization
monitoring/# Monitoring (Sentry, PostHog)
shared/ # Shared utilities and config
storage/ # File storage (S3/MinIO)
ui/ # Shared UI components
``` ```
## Quick Start Marketing + dashboard live at **claudemesh.com**; broker runs at
**ic.claudemesh.com**.
### 1. Install dependencies ---
```bash ## 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 pnpm install
```
### 2. Configure environment variables
Copy the example env files:
```bash
# Root env (database, product name, URL)
cp .env.example .env cp .env.example .env
# Web app env (auth, billing, email, storage, AI, etc.)
cp apps/web/.env.example apps/web/.env.local 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
``` ```
**Root `.env`** — minimum required variables: 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`).
```env ### Dev accounts
DATABASE_URL="postgresql://turbostarter:turbostarter@localhost:5440/core"
PRODUCT_NAME="TurboStarter"
URL="http://localhost:3000"
DEFAULT_LOCALE="en"
```
> **Note:** The database port is `5440` (mapped from Docker), not the default `5432`. After `pnpm services:setup`:
**`apps/web/.env.local`** — key variables to configure: | Role | Email | Password |
|-------|-------------------------------|------------|
| User | `me+user@turbostarter.dev` | `Pa$$w0rd` |
| Admin | `me+admin@turbostarter.dev` | `Pa$$w0rd` |
| Variable | Description | Required | ### Common commands
|---|---|---|
| `BETTER_AUTH_SECRET` | Auth token signing secret | Yes |
| `NEXT_PUBLIC_AUTH_PASSWORD` | Enable password auth (`true`/`false`) | Yes |
| `NEXT_PUBLIC_URL` | Public URL of the web app | Yes |
| `STRIPE_SECRET_KEY` | Stripe key (if using Stripe billing) | Optional |
| `RESEND_API_KEY` | Resend key (if using Resend email) | Optional |
| `S3_*` | S3/MinIO storage credentials | Optional |
| `OPENAI_API_KEY` | OpenAI key (if using AI features) | Optional |
For local MinIO storage, use these S3 settings in `apps/web/.env.local`: | 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 |
```env More in [`CONTRIBUTING.md`](./CONTRIBUTING.md).
S3_REGION="us-east-1"
S3_BUCKET="uploads"
S3_ENDPOINT="http://localhost:9000"
S3_ACCESS_KEY_ID="minioadmin"
S3_SECRET_ACCESS_KEY="minioadmin"
```
See `apps/web/.env.example` for the full list of available variables. ---
### 3. Start infrastructure (Docker Compose) ## License
Start PostgreSQL and MinIO: MIT — see [LICENSE](./LICENSE).
```bash ---
docker compose up -d
```
Wait for services to be healthy: <div align="center">
```bash **Made for swarms.** · [claudemesh.com](https://claudemesh.com)
docker compose up -d --wait
```
Or use the built-in shortcut: </div>
```bash
pnpm services:start
```
### 4. Set up the database
Run migrations and seed data:
```bash
pnpm services:setup
```
This runs `docker compose up -d --wait`, then applies database migrations and seeds initial data.
### 5. Start development
```bash
pnpm dev
```
The web app will be available at **http://localhost:3000**.
## Docker Commands
### Infrastructure Services
| Command | Description |
|---|---|
| `docker compose up -d` | Start all services (PostgreSQL + MinIO) |
| `docker compose down` | Stop all services |
| `docker compose logs -f` | Follow service logs |
| `docker compose ps` | Show service status |
Or use the pnpm shortcuts:
| Command | Description |
|---|---|
| `pnpm services:start` | Start Docker services and wait for healthy |
| `pnpm services:stop` | Stop Docker services |
| `pnpm services:logs` | Follow Docker service logs |
| `pnpm services:status` | Show Docker service status |
| `pnpm services:setup` | Start services + run DB migrations + seed |
### Service URLs
| Service | URL | Credentials |
|---|---|---|
| Web App | http://localhost:3000 | — |
| PostgreSQL | localhost:5440 | `turbostarter` / `turbostarter` |
| MinIO API | http://localhost:9000 | `minioadmin` / `minioadmin` |
| MinIO Console | http://localhost:9001 | `minioadmin` / `minioadmin` |
### Production Build (Docker)
Build and run the web app as a production Docker image:
```bash
docker build -t turbostarter-web .
docker run -p 3000:3000 --env-file apps/web/.env.local turbostarter-web
```
## Development Commands
| Command | Description |
|---|---|
| `pnpm dev` | Start all apps in development mode |
| `pnpm build` | Build all packages and apps |
| `pnpm lint` | Run ESLint across the monorepo |
| `pnpm format` | Check formatting with Prettier |
| `pnpm format:fix` | Fix formatting |
| `pnpm typecheck` | Run TypeScript type checking |
| `pnpm test` | Run tests |
| `pnpm auth:seed` | Seed auth dev accounts |
### Database Commands
Run from the root (or within `packages/db`):
| Command | Description |
|---|---|
| `pnpm --filter @turbostarter/db db:migrate` | Run database migrations |
| `pnpm --filter @turbostarter/db db:push` | Push schema changes |
| `pnpm --filter @turbostarter/db db:generate` | Generate new migration |
| `pnpm --filter @turbostarter/db db:studio` | Open Drizzle Studio |
| `pnpm --filter @turbostarter/db db:reset` | Reset database |
| `pnpm --filter @turbostarter/db db:seed` | Seed database |
## Dev Login Credentials
After running `pnpm services:setup` or `pnpm auth:seed`:
| Role | Email | Password |
|---|---|---|
| User | `me+user@turbostarter.dev` | `Pa$$w0rd` |
| Admin | `me+admin@turbostarter.dev` | `Pa$$w0rd` |