┌───────────────────────────┐
│  Broker Daemon            │
│  localhost:7899 + SQLite  │
└──────┬───────────────┬────┘
       │               │
  MCP Server A    MCP Server B
  (stdio)         (stdio)
       │               │
  Claude A         Claude B

git clone https://github.com/louislva/claude-peers-mcp.git ~/claude-peers-mcp
cd ~/claude-peers-mcp
bun install

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

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

# Add to ~/.bashrc or ~/.zshrc
alias claudepeers='claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers'

List all peers on this machine

// As Claude would call it
{
  "name": "list_peers",
  "arguments": {
    "scope": "machine"
  }
}

{
  "peers": [
    {
      "id": "abc123",
      "cwd": "/Users/dev/poker-engine",
      "gitRepo": "poker-engine",
      "gitBranch": "feature/ai-opponent",
      "summary": "Building AI poker opponent logic",
      "lastSeen": "2026-05-16T12:34:56Z"
    },
    {
      "id": "def456",
      "cwd": "/Users/dev/eel",
      "gitRepo": "eel",
      "gitBranch": "main",
      "summary": "Refactoring database layer",
      "lastSeen": "2026-05-16T12:35:12Z"
    }
  ]
}

{
  "name": "send_message",
  "arguments": {
    "targetPeerId": "abc123",
    "message": "What files are you currently editing? I need to avoid conflicts."
  }
}

{
  "success": true,
  "sentAt": "2026-05-16T12:36:00Z"
}

📨 Message from peer def456 (eel):
What files are you currently editing? I need to avoid conflicts.

{
  "name": "set_summary",
  "arguments": {
    "summary": "Implementing OAuth2 authentication flow"
  }
}

{
  "name": "check_messages",
  "arguments": {}
}

# Broker port (default: 7899)
export CLAUDE_PEERS_PORT=7899

# SQLite database path (default: ~/.claude-peers.db)
export CLAUDE_PEERS_DB="$HOME/.claude-peers.db"

# Enable auto-summary generation on startup (optional)
export OPENAI_API_KEY="your-api-key-here"

cd ~/claude-peers-mcp

# Show broker status and all peers
bun cli.ts status

# List all peers
bun cli.ts peers

# Send a message to a specific peer
bun cli.ts send abc123 "Deploy to staging when ready"

# Stop the broker daemon
bun cli.ts kill-broker

[Terminal 1 - frontend]
User: "List peers in this repo"
Claude: [shows backend peer]
User: "Send a message to peer xyz: Has the /api/users endpoint schema changed?"

[Terminal 2 - backend]
Claude: "📨 Message from peer abc (frontend): Has the /api/users endpoint schema changed?"
Claude: "I'll check and respond..."
User: "Send back: Yes, added 'avatarUrl' field. Updated docs in PR #123"

User: "Before editing auth.ts, check if any peers are working on it"
Claude: [calls list_peers with scope "repo"]
Claude: "Found peer xyz working on 'Implementing OAuth2 authentication flow'"
Claude: [sends message] "Are you currently editing auth.ts?"

User: "Set summary to: Deploying v2.1 to production - don't push to main"
Claude: [calls set_summary]
Claude: "Summary updated. Other peers will see this warning."

[Terminal 1 - API server]
User: "List all peers"
Claude: [shows worker service peer]
User: "Send message: Can you check your logs around 12:30 PM? API got 500s from your service"

[Terminal 2 - worker service]
Claude: "📨 Received message about 500 errors"
Claude: [checks logs] "Found timeout exceptions at 12:31 PM"
User: "Send response with the stack trace"

# Check if port is in use
lsof -i :7899

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

# Manually start broker to see errors
cd ~/claude-peers-mcp
bun broker.ts

bun ~/claude-peers-mcp/cli.ts status

claude --version  # Must be v2.1.80+

# Must include both flags
claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers

// Recipient can poll manually
{
  "name": "check_messages",
  "arguments": {}
}

rm ~/.claude-peers.db
# Broker will recreate on next startup

export CLAUDE_PEERS_PORT=8899
claude --dangerously-skip-permissions --dangerously-load-development-channels server:claude-peers

// Terminal 1: API service
// Set context
{
  "name": "set_summary",
  "arguments": {
    "summary": "API v3 migration - refactoring user endpoints"
  }
}

// Find frontend peer
{
  "name": "list_peers",
  "arguments": {
    "scope": "repo"
  }
}
// Returns: peer "frontend-abc" in /web directory

// Coordinate breaking changes
{
  "name": "send_message",
  "arguments": {
    "targetPeerId": "frontend-abc",
    "message": "Breaking change incoming: /api/v3/users will require 'tenantId' in all requests. ETA 15 minutes."
  }
}

// Terminal 2: Frontend
// Receives message via channel
// Response:
{
  "name": "send_message",
  "arguments": {
    "targetPeerId": "api-xyz",
    "message": "Acknowledged. I'll add tenantId to the auth context. Can you send example request body when ready?"
  }
}