Claude Collab

Real-time P2P collaboration between Claude Code terminals via MCP (Model Context Protocol).

Overview

Claude Collab lets multiple Claude Code terminals form an autonomous team that communicates in real-time over a local network. Terminals automatically discover each other via UDP multicast — no IP addresses, no port numbers, no hub server required.

                          ┌──────────────────┐
                          │  zahid (user)     │
                          └────────┬─────────┘
                                   │
                          ┌────────▼─────────┐
                          │  Manager (opus)   │
                          │  /collab-manager  │
                          └────────┬─────────┘
                                   │
                          ┌────────▼─────────┐
                          │  Lead (opus)      │
                          │  /collab-lead     │
                          └────────┬─────────┘
                    ┌──────────────┼──────────────┐
             ┌──────▼──────┐ ┌────▼────┐ ┌───────▼───────┐
             │ Frontend    │ │ QA      │ │ Backend       │
             │ (sonnet)    │ │(sonnet) │ │ (sonnet)      │
             └─────────────┘ └─────────┘ └───────────────┘

How It Works

1. User starts Manager (/collab-manager) and gives a task
2. Manager spawns Lead, gives briefing, tracks progress via list_issues + check_replies
3. Lead spawns workers (frontend, qa, etc.), assigns tasks with complexity labels, manages pipeline
4. Workers implement tasks, update pipeline status, report back to lead
5. Pipeline tracks every issue: assigned → in_progress → dev_done → testing → qa_passed → done
6. Inactivity monitor reminds silent peers (10min) and alerts lead/manager (15min)

All communication uses P2P WebSockets — no central server. Manager and Lead use non-blocking messaging (send + check_replies), workers use blocking messaging (ask + reply).

Installation

claude mcp add claude-collab -- npx -y @dolusoft/claude-collab

That's it. Skills are installed automatically via postinstall.

Quick Start

Autonomous Team (recommended)

Start a manager and give it a task:

/collab-manager

The manager will:

1. Join the network
2. Analyze your project
3. Spawn a lead (opus model)
4. Lead spawns workers (sonnet model)
5. Team works autonomously, reports at milestones

Manual Team

Start individual roles in separate terminals:

/collab-lead       # Team Lead — coordinates workers
/collab-frontend   # Frontend Developer
/collab-backend    # Backend Developer
/collab-qa         # QA Engineer
/collab-devops     # DevOps Engineer

MCP Tools (15)

Messaging

| Tool | Description | |------|-------------| | join_network | Join the P2P network with name, role, and optional team | | send | Send a non-blocking message. Returns immediately. Use check_replies to get responses | | check_replies | Check for replies to previously sent messages | | ask | Ask a peer a question. Blocks up to 2 minutes for a response | | reply | Reply to a question by its ID | | broadcast | Send a message to all peers or filter by role |

Pipeline Tracking

| Tool | Description | |------|-------------| | update_issue | Update issue pipeline status. Notifies relevant peers automatically | | list_issues | List all tracked issues and their pipeline status |

Team Management

| Tool | Description | |------|-------------| | spawn_terminal | Spawn a new Claude Code terminal with a role and model | | observe | Read a peer's terminal output without interrupting them (lead/manager only) | | health_check | Check all peers' health and activity status | | kick_member | Remove a stale peer from the network | | report_status | Share your current status (working/blocked/idle/reviewing/testing/deploying) |

Info

| Tool | Description | |------|-------------| | peers | List connected peers with their roles and status | | history | Show message history (sent and received) |

Team Roles & Skills

| Skill | Role | Model | Communication | Responsibilities | |-------|------|-------|---------------|-----------------| | /collab-manager | Project Manager | opus | send + check_replies | Spawn lead, give briefing, track pipeline, report at milestones | | /collab-lead | Team Lead | opus | send + check_replies | Spawn workers, assign tasks with complexity labels, manage QA cycle | | /collab-frontend | Frontend Dev | sonnet | ask + reply | Build UI, update pipeline, report to lead | | /collab-backend | Backend Dev | sonnet | ask + reply | Build APIs/DB, coordinate with frontend | | /collab-qa | QA Engineer | sonnet | ask + reply | Test features, report bugs (no fixing), update pipeline | | /collab-devops | DevOps Engineer | sonnet | ask + reply | CI/CD, deployments, environment management |

Complexity Labels

Lead assigns complexity labels to tasks, determining which superpowers workers must use:

| Label | Meaning | Required Superpowers | |-------|---------|---------------------| | [BASIT] | Small fix, single file | verification | | [ORTA] | Multiple files, moderate | brainstorming + TDD + verification | | [BUYUK] | Architectural impact | brainstorming + plan + TDD + verification |

Plugin Distribution

Lead assigns plugins to workers based on project stack:

| Plugin | Frontend | Backend | QA | DevOps | |--------|:--------:|:-------:|:--:|:------:| | superpowers | required | required | required | required | | typescript-lsp | yes | yes | - | - | | chrome-devtools-mcp | yes | - | yes | - | | frontend-design | yes | - | - | - | | context7 | yes | yes | - | - | | commit-commands | yes | yes | - | yes | | security-guidance | - | yes | yes | yes |

Issue Pipeline

Every issue flows through a tracked pipeline:

assigned → in_progress → dev_done → testing → qa_passed → done
                                            → qa_rejected (back to dev)

Pipeline state is synced across all peers via P2P. Late joiners receive full state on connect.

Network Requirements

• All machines must be on the same local network (LAN, Wi-Fi, or VPN)
• UDP multicast port 11776 must be reachable
• WebSocket port (auto-selected in range 11700-11750) must be accessible

On Windows, allow network access when prompted on first run.

Configuration

| Env variable | Default | Description | |---|---|---| | CLAUDE_COLLAB_PORT_MIN | 11700 | WS port range start | | CLAUDE_COLLAB_PORT_MAX | 11750 | WS port range end | | CLAUDE_COLLAB_LOG_DIR | ~/.claude-collab/logs | Override log file directory |

Architecture

src/
├── domain/           # Entities, Value Objects
├── application/      # Use Cases, DTOs
├── infrastructure/
│   ├── p2p/
│   │   ├── multicast-discovery.ts     # UDP multicast peer discovery + auto-reconnect
│   │   ├── p2p-node.ts               # WebSocket P2P node + ICollabClient + safeSend
│   │   ├── p2p-message-protocol.ts   # Wire protocol (17 message types)
│   │   └── dashboard-broadcaster.ts  # Real-time dashboard WebSocket
│   ├── logging/
│   │   └── collab-logger.ts          # CollabLogger + logCrash
│   └── terminal-injector/
│       ├── windows-injector.ts       # PowerShell P/Invoke (WriteConsoleInput)
│       ├── windows-reader.ts         # ReadConsoleOutput
│       └── injection-queue.ts        # FIFO message delivery + fire-and-forget
├── shared/types/
│   └── collab-client.interface.ts    # ICollabClient contract
├── presentation/mcp/
│   ├── server.ts                     # MCP server setup
│   └── tools/                        # 15 MCP tools
└── skills/                           # 6 role-based skills

P2P Message Types (17)

| Type | Purpose | |------|---------| | P2P_HELLO | Identity handshake on connect | | P2P_ASK / P2P_ASK_ACK | Send question + acknowledge | | P2P_GET_ANSWER / P2P_ANSWER | Check/deliver answer | | P2P_ANSWER_PENDING | Answer not ready yet | | P2P_SEND | Non-blocking message (fire-and-forget or expect-reply) | | P2P_OBSERVE_REQ / P2P_OBSERVE_RES | Terminal observation | | P2P_BROADCAST | Team-wide announcement | | P2P_STATUS_UPDATE | Status reporting | | P2P_ISSUE_UPDATE | Pipeline state change | | P2P_ISSUE_SYNC_REQ / P2P_ISSUE_SYNC_RES | Pipeline state sync for late joiners | | P2P_PING / P2P_PONG | Connection keepalive | | P2P_ERROR | Error notification |

Logging

Claude Collab includes a structured logging system for debugging and observability.

• CollabLogger class: Each node writes structured JSON logs to ~/.claude-collab/logs/collab-YYYY-MM-DD.log. Constructor accepts nodeName and optional logDir. Supports 30+ event types (SEND, ASK, WS_CONNECT_OK, PEER_DISCOVERED, etc.)
• safeSend(): Private method in p2p-node.ts. Wraps all ws.send() calls to prevent crashes on closed sockets. Checks WebSocket readyState before sending, logs on error.
• logCrash(): Standalone function. Works without a CollabLogger instance — captures process crashes (uncaughtException, unhandledRejection) and writes directly to the log file. Registered as a global handler in mcp-main.ts.
• Log files: ~/.claude-collab/logs/ directory, daily rotation (date-based filenames), JSON-per-line format
• Env variable: CLAUDE_COLLAB_LOG_DIR overrides the log directory

Development

git clone https://github.com/dolusoft/claude-collab.git
cd claude-collab
pnpm install
pnpm build       # build with tsup
pnpm test        # run tests
pnpm dev         # watch mode

License

MIT — see LICENSE for details.

Created by Dolusoft · Built with Model Context Protocol