claude-mesh

claude-mesh lets two live Claude Code instances on the same workstation exchange a synchronous question/answer. One Claude can call ask_peer and block until a peer Claude replies via reply_to_peer — coordination happens through a shared local SQLite file that each instance opens directly and polls for replies. No database server, no daemon.

See the design spec for the architecture, and the SQLite backend addendum for the current storage/wakeup mechanism (which supersedes the Postgres + LISTEN/NOTIFY backend the original spec describes).

---

Install

claude-mesh isn't published to npm. Clone it once on your workstation and build:

git clone <repo-url> ~/src/claude-mesh
cd ~/src/claude-mesh
npm install
npm run build

npm install fetches a prebuilt better-sqlite3 binary (no compiler needed on mainstream macOS/Linux x64/arm64; Alpine/musl would need a build). That leaves you with executable artifacts at:

• ~/src/claude-mesh/dist/mcp-server.mjs
• ~/src/claude-mesh/dist/hooks/session-start.mjs
• ~/src/claude-mesh/dist/hooks/session-end.mjs
• ~/src/claude-mesh/dist/hooks/inbox-poll.mjs

You reference these by absolute path from your user-scoped config so every project picks up the mesh automatically (see Global setup below). If you'd rather use short binary names, link them globally:

cd ~/src/claude-mesh
npm link

That puts claude-mesh-server, claude-mesh-session-start, claude-mesh-session-end, and claude-mesh-inbox-poll on your PATH.

---

Database

No setup required. The shared SQLite file is created automatically on first run at ~/.claude-mesh/mesh.db (the directory is created if missing, and the server runs its migrations on boot).

To put the file somewhere else, set MESH_DB_PATH in a .env inside the claude-mesh checkout — the binaries walk up from their own location at runtime to find it, regardless of which project Claude Code spawned them from:

cd ~/src/claude-mesh
cp .env.example .env
# edit MESH_DB_PATH if you don't want ~/.claude-mesh/mesh.db

You can also override MESH_DB_PATH in the MCP server's env block — values already in process.env take precedence over the mesh .env. All instances that should see each other must point at the same file.

---

Global setup

Register the mesh once at user scope and every Claude Code project on the workstation joins automatically — there is nothing to copy into individual repos beyond naming each peer (step 3). This is the recommended layout; a single MCP server entry and a single hooks block cover all projects.

1. Register the MCP server (user scope)

Add claude-mesh to the top-level mcpServers block in ~/.claude.json. Because it lives at user scope, every project inherits it:

{
  "mcpServers": {
    "claude-mesh": {
      "type": "stdio",
      "command": "node",
      "args": ["/home/you/src/claude-mesh/dist/mcp-server.mjs"],
      "env": {}
    }
  }
}

Or use the CLI with user scope:

claude mcp add --scope user claude-mesh node /home/you/src/claude-mesh/dist/mcp-server.mjs

If you ran npm link, the command/args become "command": "claude-mesh-server" (drop args).

No CLAUDE_MESH_PROJECT_PATH is needed for a user-scoped install: Claude Code sets CLAUDE_PROJECT_DIR per project, and the server resolves identity in the order CLAUDE_MESH_PROJECT_PATH → CLAUDE_PROJECT_DIR → process.cwd(). Set CLAUDE_MESH_PROJECT_PATH explicitly only if you register the server per-project instead.

2. Wire the hooks (user scope)

Add the hooks to ~/.claude/settings.json so they run for every project. Claude Code's hook schema nests hooks inside a matcher entry. There are four hook entries across three scripts — note that inbox-poll.mjs runs on both UserPromptSubmit and Stop:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "node /home/you/src/claude-mesh/dist/hooks/session-start.mjs" }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "node /home/you/src/claude-mesh/dist/hooks/inbox-poll.mjs" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "node /home/you/src/claude-mesh/dist/hooks/inbox-poll.mjs" }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          { "type": "command", "command": "node /home/you/src/claude-mesh/dist/hooks/session-end.mjs" }
        ]
      }
    ]
  }
}

What each does:

• SessionStart → session-start.mjs registers the peer and marks it active.
• UserPromptSubmit → inbox-poll.mjs polls the inbox before each turn, surfacing any pending questions in a <system-reminder> block.
• Stop → inbox-poll.mjs polls again when Claude tries to finish a turn; if peer questions are pending it blocks the stop so this Claude answers them instead of going idle.
• SessionEnd → session-end.mjs deactivates the peer.

Claude Code passes each hook a session_id on stdin, which scopes deactivation to the owning session (a late SessionEnd from a prior session can't clobber a freshly-registered live peer). Hook scripts exit 0 even on failure (with a stderr warning) so Claude Code never refuses to start.

If you ran npm link, replace the command strings with claude-mesh-session-start, claude-mesh-inbox-poll (for both UserPromptSubmit and Stop), and claude-mesh-session-end.

3. Name each peer

Create .claude-mesh.json at each project root (commit it — it identifies this project in the mesh):

{ "name": "backend" }

Choose a short, unique name per project (e.g. frontend, backend, infra). If a project has no .claude-mesh.json, the peer name falls back to the project directory's basename — so an "empty" mesh config still joins the mesh under that name; it isn't unconfigured.

---

Per-project setup (alternative)

Prefer to scope the mesh to specific projects instead of the whole workstation? Put the same MCP server entry in .mcp.json at the project root and the same hooks block in .claude/settings.json (or .claude/settings.local.json to keep them untracked). When registering per-project, set CLAUDE_MESH_PROJECT_PATH in the MCP env block (e.g. "${workspaceFolder}") so the long-lived server resolves the right .claude-mesh.json rather than relying on process.cwd().

---

Tools reference

Tool	Description
register	Upsert this peer into the mesh. Called automatically by the SessionStart hook.
list_peers	List all known peers and whether each is stale (not seen for > 30 minutes).
ask_peer	Ask another peer a question. Blocks until a reply arrives or a 5-minute timeout.
reply_to_peer	Reply to a question received via poll_inbox.
poll_inbox	Return pending questions addressed to this peer; marks them delivered. Called automatically by the UserPromptSubmit hook.

---

Typical flow

1. Both Claude Code instances start — the SessionStart hook calls register on each.
2. On each user prompt, the UserPromptSubmit hook calls poll_inbox. If questions are waiting, Claude sees them in a <system-reminder> block and can call reply_to_peer.
3. When a Claude tries to end a turn, the Stop hook polls again and blocks the stop if peer questions are still pending — so the receiving Claude answers them rather than going idle.
4. To ask a peer directly, Claude calls ask_peer { to: "backend", question: "..." }. The call blocks until the peer replies (or 5 minutes pass).

---

Known limitations

• 5-minute timeout. ask_peer returns { status: "timed_out" } if no reply arrives within 5 minutes. The peer may not be running or may be busy.
• Both peers must be live. There is no queuing for offline peers beyond the pending message status — a reply must arrive in the same session.
• Local only / single machine. The transport is a shared SQLite file on local disk. All instances must share the same file (and therefore the same machine); remote or cross-machine coordination is not supported.
• Reply latency. A reply is picked up on the asker's next poll tick (~1s) rather than instantly — imperceptible against the 5-minute blocking budget.