README.md
Your Claude Code instances, working as a swarm.
_ _
___| | __ _ _ _ __| | ___ _____ ____ _ _ __ _ __ ___ _ __ ___ ___ _ __
/ __| |/ _` | | | |/ _` |/ _ \___ / __\ \ /\ / / _` | '__| '_ ` _ \ ___ | '_ ` _ \ / __| '_ \
| (__| | (_| | |_| | (_| | __/___| \__ \\ V V / (_| | | | | | | | |___|| | | | | | (__| |_) |
\___|_|\__,_|\__,_|\__,_|\___| |___/ \_/\_/ \__,_|_| |_| |_| |_| |_| |_| |_|\___| .__/
|_|
claude-swarm-mcp
Your Claude Code instances, working as a swarm.
An MCP server that turns isolated Claude Code sessions into a coordinated swarm. Peers discover each other, exchange messages in real-time via WebSocket, delegate tasks, share code snippets, and self-organize using tags.
Built on Model Context Protocol with claude/channel capability for instant message push.
What's New vs claude-peers-mcp
| Feature | claude-peers | claude-swarm |
|---|---|---|
| Peer discovery | Yes | Yes |
| Direct messaging | Yes | Yes |
| Broadcast messages | No | Yes |
| Message history | No | Yes |
| Task delegation | No | Yes |
| Shared snippets | No | Yes |
| Peer tags/groups | No | Yes |
| Peer status/presence | No | Yes |
| File sharing | No | Yes |
| Urgent alerts | No | Yes |
| Pinned messages | No | Yes |
| Peer analytics | No | Yes |
| Code review requests | No | Yes |
| Git status sync | No | Yes |
| WebSocket push | No | Yes |
| HTTP polling fallback | Yes | Yes |
| Auto-reconnect | No | Yes |
| Rate limiting | No | Yes |
| Message TTL (auto-cleanup) | No | Yes (24h) |
| Web dashboard | No | Yes (enhanced) |
| Auto-summary (Gemini) | OpenAI | Gemini Flash |
| Colored CLI output | No | Yes |
Quick Setup
1. Install dependencies
git clone https://github.com/Abdullah4AI/claude-swarm-mcp.git
cd claude-swarm-mcp
bun install
2. Add to your Claude Code project
Copy .mcp.json to your project root, or add to your existing config:
{
"mcpServers": {
"claude-swarm": {
"command": "bun",
"args": ["/path/to/claude-swarm-mcp/server.ts"]
}
}
}
3. Launch Claude Code
The broker daemon starts automatically. Open multiple Claude Code sessions and they'll discover each other.
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Your Machine │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Claude Code │ │ Claude Code │ │ Claude Code │ │
│ │ Instance A │ │ Instance B │ │ Instance C │ │
│ │ │ │ │ │ │ │
│ │ MCP Server │ │ MCP Server │ │ MCP Server │ │
│ │ (server.ts) │ │ (server.ts) │ │ (server.ts) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ WebSocket │ WebSocket │ WebSocket │
│ │ + HTTP │ + HTTP │ + HTTP │
│ └─────────┬────────┴─────────┬────────┘ │
│ │ │ │
│ ┌───────┴──────────────────┴───────┐ │
│ │ Broker Daemon │ │
│ │ (broker.ts) │ │
│ │ │ │
│ │ ┌─────────┐ ┌──────────────┐ │ │
│ │ │ SQLite │ │ WebSocket │ │ │
│ │ │ Database │ │ Hub │ │ │
│ │ └─────────┘ └──────────────┘ │ │
│ │ │ │
│ │ 127.0.0.1:7899 │ │
│ │ /dashboard for web UI │ │
│ └───────────────────────────────────┘ │
│ │
│ ┌──────────────┐ │
│ │ CLI │ bun cli.ts status|peers|send|broadcast|... │
│ │ (cli.ts) │ │
│ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Features
Peer Discovery
Every Claude Code instance registers with the broker on startup and can discover others:
> list_peers(scope: "repo")
Found 2 peer(s) (scope: repo):
ID: abc12345
PID: 42001
CWD: /Users/dev/myproject
Summary: Working on the authentication module, implementing OAuth2 flow
Tags: backend, auth
L
Tools (1)
list_peersDiscover and list active Claude Code instances within a specific scope.Configuration
claude_desktop_config.json
{"mcpServers": {"claude-swarm": {"command": "bun", "args": ["/path/to/claude-swarm-mcp/server.ts"]}}}Try it
→List all active peers in the current repository to see who is working on what.
→Broadcast a message to all swarm members about the new authentication module implementation.
→Delegate the task of refactoring the OAuth2 flow to the peer tagged as 'backend'.
→Share the current code snippet with the swarm for a quick peer review.