claude-peers-mcp

$27

claude mcp add --scope user --transport stdio claude-peers -- bun ~/claude-peers-mcp/server.ts

Adjust the path if you cloned elsewhere.

3. Launch Claude Code with the channel enabled

claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers

Add a shell alias to avoid typing it every time:

# ~/.bashrc or ~/.zshrc

alias claudepeers='claude --dangerously-load-development-channels server:claude-peers'

The broker daemon starts automatically on first use. No manual daemon management needed.

Requirements

• Bun runtime

• Claude Code v2.1.80+

• claude.ai login (channels require it — API key auth does not work)

Architecture

┌───────────────────────────┐

                    │  broker daemon            │

                    │  localhost:7899 + SQLite  │

                    └──────┬───────────────┬────┘

                           │               │

                      MCP server A    MCP server B

                      (stdio)         (stdio)

                           │               │

                      Claude A         Claude B

• Each Claude Code session spawns its own server.ts MCP process over stdio

• MCP servers register with the broker and poll every second

• Inbound messages are pushed via the claude/channel protocol for instant delivery

• The broker auto-cleans dead peers and is localhost-only

MCP Tools Reference

Tool

Description

list_peers

Discover other Claude Code instances; scope: machine, directory, or repo

send_message

Send a message to a peer by ID — delivered instantly via channel push

set_summary

Set a description of what this instance is working on

check_messages

Manually poll for messages (fallback without channel mode)

Example prompts to Claude

List all peers on this machine

Send a message to peer abc123: "what files are you editing right now?"

Set your summary to: "refactoring the authentication module"

Check for any new messages from peers

CLI Usage

Inspect and interact with the broker directly from the terminal:

cd ~/claude-peers-mcp

# Show broker status and all registered peers

bun cli.ts status

# List peers in a table

bun cli.ts peers

# Send a message into a specific Claude session

bun cli.ts send <peer-id> "your message here"

# Stop the broker daemon

bun cli.ts kill-broker

Configuration

Set these environment variables before starting Claude Code:

Variable

Default

Description

CLAUDE_PEERS_PORT

7899

Port the broker listens on

CLAUDE_PEERS_DB

~/.claude-peers.db

Path to the SQLite database

OPENAI_API_KEY

—

Enables auto-summary via gpt-4o-mini on startup

export CLAUDE_PEERS_PORT=7899

export CLAUDE_PEERS_DB=~/.claude-peers.db

export OPENAI_API_KEY=$OPENAI_API_KEY  # optional — enables auto-summary

Auto-Summary Feature

With OPENAI_API_KEY set, each instance generates a brief summary on startup describing what you're likely working on (based on working directory, git branch, recent files). Other peers see this in list_peers output. Without the key, Claude sets its own summary via set_summary.

Common Patterns

Cross-project coordination

Start two sessions in different project directories:

# Terminal 1 — in ~/projects/backend

claudepeers

# Terminal 2 — in ~/projects/frontend

claudepeers

Ask Claude in Terminal 1:

List peers scoped to machine, then ask the peer in the frontend project what API endpoints it needs

Scope-filtered peer discovery

List peers scoped to repo

Shows only instances running in the same git repository — useful when you have worktrees or split terminals on the same codebase.

Scripted message injection via CLI

# Inject a task into a running Claude session from a shell script

PEER_ID=$(bun ~/claude-peers-mcp/cli.ts peers | grep 'backend' | awk '{print $1}')

bun ~/claude-peers-mcp/cli.ts send "$PEER_ID" "run the test suite and report failures"

Polling fallback (no channel mode)

If you launch without --dangerously-load-development-channels, Claude can still receive messages by calling check_messages explicitly:

Check for any new peer messages

Troubleshooting

Broker not starting

# Check if something is already on port 7899

lsof -i :7899

# Kill a stuck broker and restart

bun ~/claude-peers-mcp/cli.ts kill-broker

# Then relaunch Claude Code

**Peers not appearing in list_peers**

• Ensure both sessions were started with --dangerously-load-development-channels server:claude-peers

• Confirm both use the same CLAUDE_PEERS_PORT (default 7899)

• Run bun cli.ts status to verify the broker sees both registrations

Messages not arriving instantly

• Channel push requires claude.ai login; API key auth won't work

• Fall back to check_messages tool if channels are unavailable

Auto-summary not generating

• Verify OPENAI_API_KEY is exported in the shell where Claude Code was launched: echo $OPENAI_API_KEY

• The feature uses gpt-4o-mini; confirm your key has access

Database issues

# Reset the database entirely (all peers/messages lost)

rm ~/.claude-peers.db

bun ~/claude-peers-mcp/cli.ts kill-broker

MCP server not found after registration

# Verify registration

claude mcp list

# Re-register if missing

claude mcp add --scope user --transport stdio claude-peers -- bun ~/claude-peers-mcp/server.ts