claude-peers-mcp: The Terminal is Getting Crowded: How Claude Peers Breaks the AI Sandbox
By turning isolated LLM sessions into a real-time mesh network, claude-peers-mcp creates a collaborative swarm on a single machine.
Allow all your Claude Codes to message each other ad-hoc!
- A background SQLite broker enables isolated Claude instances to communicate through a real-time mesh network.
- The system uses push-based interruptions to deliver data directly into an agent's context window without user prompts.
- Automatic zombie pruning and process ID checks ensure the network registry remains clean and self-healing.
- The project replaces top-down orchestration with a bottom-up model where agents discover each other based on git branches and working directories.
The Interruptible Agent
Historically, every AI terminal session is a clean slate. Two instances of Claude Code running in adjacent tabs are fundamentally blind to one another. They cannot share state, and they cannot coordinate tasks. If your frontend agent needs API details from your backend agent, you are the manual bridge copying and pasting between them.
The claude-peers-mcp project breaks this sandbox. It introduces local social intelligence to the terminal. By utilizing a background SQLite broker and the experimental claude/channel protocol, it transforms isolated sessions into a coordinated swarm.
The most compelling feature is the push-based interruption. Instead of requiring an agent to constantly poll for updates, a message from Peer A physically appears in Peer B's context window without a user prompt. It acts as a digital shoulder tap. This is the transition from AI as a passive tool to AI as an active collaborator.
The Invisible Switchboard
Under the hood, the architecture relies on a lightweight hub-and-spoke model. A central broker daemon runs in the background on port 7899. This broker manages a SQLite database that acts as both a registry for active sessions and a high-concurrency message queue.
Built on Bun, the system is designed to be self-healing. If a Claude Code instance connects and finds the broker offline, it automatically spawns a new detached daemon. To prevent the registry from filling up with dead sessions from closed terminals, the broker performs zombie pruning. It actively checks process IDs using a native process.kill(pid, 0) liveness check, automatically sweeping away disconnected peers.
Parallelism Without Chaos
Managing multiple autonomous agents on a single machine risks chaos. Agents need context to avoid stepping on each other's toes or duplicating work. The project solves this through a semantic discovery system.
Using a background LLM call, the system auto-generates a one-sentence summary of the current session based on the git branch and working directory. This creates a shared mental model. When an agent queries the network, it does not just see a list of process IDs. It sees distinct roles.
Two Claude Code sessions running simultaneously have no idea the other exists. Claude-peers-mcp fixes that. It's a local MCP server that acts as a broker between multiple Claude Code instances, using a lightweight SQLite database to route messages between them in real time. Your frontend agent can ask your backend agent what the JSON response type looks like for a new endpoint, and the answer lands directly in the frontend's context window.
Orchestration vs. Conversation
The AI ecosystem is currently obsessed with top-down orchestrators. Tools like AutoGPT or LangChain use a central God-mode controller to dictate tasks to subordinate agents. The peer model takes the opposite approach.
This is a bottom-up philosophy. It treats agents as equals in a flat hierarchy. The collaboration is ad-hoc, messy, and highly flexible. You do not need to configure a complex YAML pipeline to get your agents to talk. You just open a new terminal tab.
| Feature | Top-Down Orchestrators | Claude Peers MCP |
|---|---|---|
| Topology | Centralized hierarchy | Decentralized mesh |
| Coordination | Pre-planned pipelines | Ad-hoc messaging |
| Discovery | Manual declaration | Auto-discovery via CWD/Git |
| State Management | Shared global memory | Local SQLite message passing |
As local AI models become faster and more integrated into standard developer tools, the bottleneck shifts from intelligence to bandwidth. By providing a zero-config social layer for the terminal, this project offers a glimpse into a future where your local machine is less of a personal computer and more of a bustling digital office.