claude-nexus: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

claude-nexus

Peer discovery and messaging MCP channel for Claude Code instances. When several Claude Code sessions run on one machine, each can discover the others and exchange messages that arrive instantly via the claude/channel protocol.

Commands

bun install                     # install dependencies

# Run components directly
bun broker.ts                   # start the broker daemon manually (normally auto-launched)
bun server.ts                   # run the MCP stdio server (normally spawned by Claude Code)

# CLI (inspect/interact with a running broker)
bun cli.ts status               # broker health + all registered peers
bun cli.ts peers                # list peers
bun cli.ts send <peer-id> <msg> # inject a message into a peer's session
bun cli.ts kill-broker          # stop the broker daemon

# Tests
bun test                        # run all tests
bun test <file>                 # run a single test file

There is no build step, linter, or test suite committed yet — TypeScript runs directly under Bun. tsconfig.json is noEmit with strict on (used for type-checking/editor only).

Running with Claude Code

# Full experience (instant channel push of inbound messages):
claude --dangerously-load-development-channels server:claude-nexus

# As a plain MCP (tools work, but no automatic push) — via .mcp.json:
#   { "claude-nexus": { "command": "bun", "args": ["./server.ts"] } }

Requires Claude Code v2.1.80+ and a claude.ai login (channels do not work with API-key auth).

Architecture

Two processes cooperate over localhost HTTP:

• broker.ts — a singleton daemon on 127.0.0.1:7899 backed by a SQLite DB (bun:sqlite, WAL mode). Owns the peers and messages tables and routes all traffic. One per machine.
• server.ts — an MCP stdio server, one spawned per Claude Code instance. On startup it calls ensureBroker() (auto-launches broker.ts detached via Bun.spawn(...).unref() if /health is unreachable), registers itself, then runs two timers: a 1s poll for inbound messages and a 15s heartbeat.
• shared/types.ts — the broker's HTTP request/response contract, imported by both sides. Change a payload here and update broker.ts handlers + server.ts/cli.ts callers together.
• shared/summarize.ts — best-effort auto-summary of what an instance is working on (see below).
• cli.ts — standalone HTTP client for the broker; uses the same endpoints as the server. It sends messages with from_id: "cli" (a synthetic sender, not a registered peer).
• index.ts — module marker only; there is no single library entry point.