@dolusoft/claude-collab 1.11.4 → 1.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (14) hide show
  1. package/README.md +250 -226
  2. package/dist/cli.js +4405 -664
  3. package/dist/cli.js.map +1 -1
  4. package/dist/mcp-main.js +4455 -673
  5. package/dist/mcp-main.js.map +1 -1
  6. package/package.json +84 -80
  7. package/scripts/setup-skills.mjs +54 -0
  8. package/skills/collab-backend/SKILL.md +72 -0
  9. package/skills/collab-devops/SKILL.md +66 -0
  10. package/skills/collab-frontend/SKILL.md +122 -0
  11. package/skills/collab-lead/SKILL.md +237 -0
  12. package/skills/collab-manager/SKILL.md +253 -0
  13. package/skills/collab-observer/SKILL.md +121 -0
  14. package/skills/collab-qa/SKILL.md +113 -0
package/README.md CHANGED
@@ -1,226 +1,250 @@
1
- # Claude Collab
2
-
3
- Real-time collaboration between Claude Code terminals via MCP (Model Context Protocol).
4
-
5
- [![npm version](https://badge.fury.io/js/@dolusoft%2Fclaude-collab.svg)](https://www.npmjs.com/package/@dolusoft/claude-collab)
6
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
-
8
- ## Overview
9
-
10
- Claude Collab lets multiple Claude Code terminals communicate directly — no central server needed. Each node listens on a fixed port (12345). Peers connect manually by IP address and form a **full mesh**: when you connect to one peer, everyone connects to everyone automatically.
11
-
12
- ```
13
- alice ◄──────────────────► bob
14
- direct WebSocket
15
- (manual IP connect)
16
- │
17
- ▼
18
- carol
19
- (auto-connected via mesh)
20
- ```
21
-
22
- ## Setup
23
-
24
- ### Step 1 — Add to Claude Code (each machine, one time)
25
-
26
- ```bash
27
- claude mcp add claude-collab -- npx -y @dolusoft/claude-collab --name <your-name>
28
- ```
29
-
30
- | Placeholder | What to put |
31
- |-------------|-------------|
32
- | `<your-name>` | Your identifier on the network (e.g. `alice`, `backend`, `frontend`) |
33
-
34
- ### Step 2 — Find your IP
35
-
36
- Call `status()` in Claude Code:
37
-
38
- ```
39
- status()
40
- ```
41
-
42
- This shows your LAN IP address. Share it with your teammate.
43
-
44
- ### Step 3 — Connect to a peer
45
-
46
- Your teammate calls `connect()` with your IP:
47
-
48
- ```
49
- connect("192.168.1.5")
50
- ```
51
-
52
- On the **first call only**, a Windows UAC popup appears — click **Yes** to open port 12345 on your firewall. This stays open permanently.
53
-
54
- ### Step 4 — Full mesh forms automatically
55
-
56
- If Alice is already connected to Bob, and Carol connects to Alice — Carol automatically connects to Bob as well. No extra steps needed.
57
-
58
- ### Step 5 — After a disconnect or restart
59
-
60
- The disconnecting peer calls `connect(ip)` again to rejoin. Others do not need to do anything.
61
-
62
- ---
63
-
64
- ## MCP Tools
65
-
66
- | Tool | Description |
67
- |------|-------------|
68
- | `connect` | Connect to a peer by their LAN IP. Opens firewall on first use (UAC popup). |
69
- | `status` | Show your name, LAN IP, port, and connected peers. |
70
- | `ask` | Ask a peer a question by name. Waits up to 5 minutes for a reply. |
71
- | `reply` | Reply to an incoming question. |
72
- | `history` | Show past questions and answers from this session. |
73
-
74
- ## Example
75
-
76
- ```
77
- # Alice checks her IP and shares it with Bob
78
- status()
79
- # → Name: alice IP: 192.168.1.5 Port: 12345
80
-
81
- # Bob connects to Alice
82
- connect("192.168.1.5")
83
- # → Connected to "alice". Use status() to see all connected peers.
84
-
85
- # Bob asks Alice a question
86
- ask("alice", "What's the response format for the /users endpoint?")
87
-
88
- # Alice sees the question injected into her terminal and replies
89
- reply("<question-id>", "Returns JSON: { id, name, email }")
90
-
91
- # Bob receives the answer
92
- ```
93
-
94
- ## Use Case: Sharing Context Between Agents
95
-
96
- Claude Code works best when focused on a single context — one terminal per feature, service, or role. But when multiple Claude instances work in parallel, they can't share what they know.
97
-
98
- **Claude Collab bridges that gap.** If a user told Alice Claude Code about an API key 10 messages ago, Bob Claude Code can ask Alice Claude Code directly — and Alice Claude Code answers from her own conversation context. No copy-paste. No switching tabs. The knowledge travels between agents.
99
-
100
- Alice Claude Code and Bob Claude Code are both connected via Claude Collab. During Alice Claude Code's session, the user manually entered an API key:
101
-
102
- > *"My API key is sk-abc123..."*
103
-
104
- This is now part of Alice Claude Code's context. Bob Claude Code doesn't know — he's been working in a separate terminal and needs the key to make API calls.
105
-
106
- Bob Claude Code asks Alice Claude Code directly:
107
-
108
- ```
109
- ask("alice", "What is the API key?")
110
- ```
111
-
112
- Alice Claude Code's terminal receives the question, and she replies from what she already knows:
113
-
114
- ```
115
- reply("<question-id>", "sk-abc123...")
116
- ```
117
-
118
- Bob Claude Code gets the answer and continues working — without the user having to repeat themselves.
119
-
120
- ```mermaid
121
- sequenceDiagram
122
- participant User
123
- participant Alice Claude Code
124
- participant Bob Claude Code
125
-
126
- Alice Claude Code->>Alice Claude Code: status()
127
- Note over Alice Claude Code: IP: 192.168.1.5
128
-
129
- Bob Claude Code->>Alice Claude Code: connect("192.168.1.5")
130
- Note over Bob Claude Code: UAC popup → firewall opens (once)
131
- Alice Claude Code-->>Bob Claude Code: HELLO_ACK
132
- Note over Alice Claude Code,Bob Claude Code: Direct connection established
133
-
134
- User->>Alice Claude Code: "My API key is sk-abc123..."
135
- Note over Alice Claude Code: Stored in context
136
-
137
- Bob Claude Code->>Alice Claude Code: ask("alice", "What is the API key?")
138
- Alice Claude Code-->>Bob Claude Code: ASK_ACK
139
- Note over Alice Claude Code: Question injected into terminal
140
- Alice Claude Code->>Bob Claude Code: reply(questionId, "sk-abc123...")
141
- Note over Bob Claude Code: Uses API key
142
- ```
143
-
144
- ---
145
-
146
- ## How it works
147
-
148
- ```
149
- Startup:
150
- Each node binds a WebSocket server on fixed port 12345
151
- If the port is already in use, the existing process is killed automatically
152
-
153
- Connecting:
154
- connect("IP") → opens firewall (first time only, UAC popup) → WebSocket handshake
155
- After handshake: both sides exchange PEER_LIST
156
- Each side connects to any unknown peers in the list (full mesh)
157
- Existing peers are notified via PEER_ANNOUNCE and connect directly too
158
-
159
- Questions:
160
- ask() → sends ASK to peer → peer gets question injected into their terminal
161
- reply() → sends ANSWER back → ask() call unblocks immediately (push, no polling)
162
- ```
163
-
164
- ## Limitations
165
-
166
- - **Windows only** — terminal injection uses `kernel32.dll` Win32 APIs (`AttachConsole`, `WriteConsoleInput`) compiled via PowerShell. macOS and Linux are not supported.
167
- - **IP reachability required** — peers must be able to reach each other's IP on port 12345. Works on the same LAN, or any network where routing is possible (VPN, etc.).
168
- - **No encryption** — peer connections use plain `ws://` WebSocket. Traffic is unencrypted on the network.
169
- - **5-minute answer timeout** — if the peer does not reply within 5 minutes, `ask()` times out. The question is not retried automatically.
170
- - **One queued answer per offline peer** — if a peer is offline and you reply to multiple questions from them, only the last reply is queued and delivered on reconnect.
171
- - **No persistence** — all questions, answers, and history are stored in memory. Restarting the process clears everything.
172
- - **No broadcast** — `ask()` targets a single peer by name. There is no tool to send a message to all peers at once.
173
- - **Peer names are not unique** — if two peers join with the same name, the second connection is silently dropped.
174
-
175
- ---
176
-
177
- ## Development
178
-
179
- ```bash
180
- git clone https://github.com/dolusoft/claude-collab.git
181
- cd claude-collab
182
- pnpm install
183
- pnpm build # tsup → dist/mcp-main.js + dist/cli.js
184
- pnpm typecheck # tsc --noEmit
185
- pnpm test # vitest unit tests
186
- ```
187
-
188
- ### Testing locally with two peers
189
-
190
- Open two terminals on the same machine and run:
191
-
192
- ```bash
193
- # Terminal 1
194
- node dist/mcp-main.js --name alice
195
-
196
- # Terminal 2
197
- node dist/mcp-main.js --name bob
198
- ```
199
-
200
- Then in terminal 2, call `connect("127.0.0.1")` — both nodes will connect on port 12345.
201
-
202
- ### Project structure
203
-
204
- ```
205
- src/
206
- ├── infrastructure/
207
- │ ├── mesh/
208
- │ │ ├── mesh-node.ts # WS server + client + peer management + mesh logic
209
- │ │ └── protocol.ts # Wire protocol: HELLO, PEER_LIST, PEER_ANNOUNCE, ASK, ANSWER
210
- │ ├── firewall/
211
- │ │ └── firewall.ts # Windows Firewall via UAC-elevated netsh
212
- │ └── terminal-injector/
213
- │ └── windows-injector.ts # Injects questions into Claude Code via WriteConsoleInput
214
- └── presentation/
215
- └── mcp/
216
- ├── server.ts # MCP server setup
217
- └── tools/ # connect, status, ask, reply, history
218
- ```
219
-
220
- ## License
221
-
222
- MIT — see [LICENSE](LICENSE) for details.
223
-
224
- ---
225
-
226
- Created by [Dolusoft](https://github.com/dolusoft) · Built with [Model Context Protocol](https://modelcontextprotocol.io)
1
+ # Claude Collab
2
+
3
+ Real-time P2P collaboration between Claude Code terminals via MCP (Model Context Protocol).
4
+
5
+ [![npm version](https://badge.fury.io/js/@dolusoft%2Fclaude-collab.svg)](https://www.npmjs.com/package/@dolusoft/claude-collab)
6
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
+
8
+ ## Overview
9
+
10
+ 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.
11
+
12
+ ```
13
+ ┌──────────────────┐
14
+ │ zahid (user) │
15
+ └────────┬─────────┘
16
+ │
17
+ ┌────────▼─────────┐
18
+ │ Manager (opus) │
19
+ │ /collab-manager │
20
+ └────────┬─────────┘
21
+ │
22
+ ┌────────▼─────────┐
23
+ │ Lead (opus) │
24
+ │ /collab-lead │
25
+ └────────┬─────────┘
26
+ ┌──────────────┼──────────────┐
27
+ ┌──────▼──────┐ ┌────▼────┐ ┌───────▼───────┐
28
+ │ Frontend │ │ QA │ │ Backend │
29
+ │ (sonnet) │ │(sonnet) │ │ (sonnet) │
30
+ └─────────────┘ └─────────┘ └───────────────┘
31
+ ```
32
+
33
+ ## How It Works
34
+
35
+ 1. **User** starts Manager (`/collab-manager`) and gives a task
36
+ 2. **Manager** spawns Lead, gives briefing, tracks progress via `list_issues` + `check_replies`
37
+ 3. **Lead** spawns workers (frontend, qa, etc.), assigns tasks with complexity labels, manages pipeline
38
+ 4. **Workers** implement tasks, update pipeline status, report back to lead
39
+ 5. **Pipeline** tracks every issue: `assigned` → `in_progress` → `dev_done` → `testing` → `qa_passed` → `done`
40
+ 6. **Inactivity monitor** reminds silent peers (10min) and alerts lead/manager (15min)
41
+
42
+ All communication uses P2P WebSockets — no central server. Manager and Lead use **non-blocking messaging** (`send` + `check_replies`), workers use **blocking messaging** (`ask` + `reply`).
43
+
44
+ ## Installation
45
+
46
+ ```bash
47
+ claude mcp add claude-collab -- npx -y @dolusoft/claude-collab
48
+ ```
49
+
50
+ That's it. Skills are installed automatically via `postinstall`.
51
+
52
+ ## Quick Start
53
+
54
+ ### Autonomous Team (recommended)
55
+
56
+ Start a manager and give it a task:
57
+
58
+ ```
59
+ /collab-manager
60
+ ```
61
+
62
+ The manager will:
63
+ 1. Join the network
64
+ 2. Analyze your project
65
+ 3. Spawn a lead (opus model)
66
+ 4. Lead spawns workers (sonnet model)
67
+ 5. Team works autonomously, reports at milestones
68
+
69
+ ### Manual Team
70
+
71
+ Start individual roles in separate terminals:
72
+
73
+ ```
74
+ /collab-lead # Team Lead — coordinates workers
75
+ /collab-frontend # Frontend Developer
76
+ /collab-backend # Backend Developer
77
+ /collab-qa # QA Engineer
78
+ /collab-devops # DevOps Engineer
79
+ ```
80
+
81
+ ## MCP Tools (15)
82
+
83
+ ### Messaging
84
+
85
+ | Tool | Description |
86
+ |------|-------------|
87
+ | `join_network` | Join the P2P network with name, role, and optional team |
88
+ | `send` | Send a non-blocking message. Returns immediately. Use `check_replies` to get responses |
89
+ | `check_replies` | Check for replies to previously sent messages |
90
+ | `ask` | Ask a peer a question. Blocks up to 2 minutes for a response |
91
+ | `reply` | Reply to a question by its ID |
92
+ | `broadcast` | Send a message to all peers or filter by role |
93
+
94
+ ### Pipeline Tracking
95
+
96
+ | Tool | Description |
97
+ |------|-------------|
98
+ | `update_issue` | Update issue pipeline status. Notifies relevant peers automatically |
99
+ | `list_issues` | List all tracked issues and their pipeline status |
100
+
101
+ ### Team Management
102
+
103
+ | Tool | Description |
104
+ |------|-------------|
105
+ | `spawn_terminal` | Spawn a new Claude Code terminal with a role and model |
106
+ | `observe` | Read a peer's terminal output without interrupting them (lead/manager only) |
107
+ | `health_check` | Check all peers' health and activity status |
108
+ | `kick_member` | Remove a stale peer from the network |
109
+ | `report_status` | Share your current status (working/blocked/idle/reviewing/testing/deploying) |
110
+
111
+ ### Info
112
+
113
+ | Tool | Description |
114
+ |------|-------------|
115
+ | `peers` | List connected peers with their roles and status |
116
+ | `history` | Show message history (sent and received) |
117
+
118
+ ## Team Roles & Skills
119
+
120
+ | Skill | Role | Model | Communication | Responsibilities |
121
+ |-------|------|-------|---------------|-----------------|
122
+ | `/collab-manager` | Project Manager | opus | `send` + `check_replies` | Spawn lead, give briefing, track pipeline, report at milestones |
123
+ | `/collab-lead` | Team Lead | opus | `send` + `check_replies` | Spawn workers, assign tasks with complexity labels, manage QA cycle |
124
+ | `/collab-frontend` | Frontend Dev | sonnet | `ask` + `reply` | Build UI, update pipeline, report to lead |
125
+ | `/collab-backend` | Backend Dev | sonnet | `ask` + `reply` | Build APIs/DB, coordinate with frontend |
126
+ | `/collab-qa` | QA Engineer | sonnet | `ask` + `reply` | Test features, report bugs (no fixing), update pipeline |
127
+ | `/collab-devops` | DevOps Engineer | sonnet | `ask` + `reply` | CI/CD, deployments, environment management |
128
+
129
+ ### Complexity Labels
130
+
131
+ Lead assigns complexity labels to tasks, determining which superpowers workers must use:
132
+
133
+ | Label | Meaning | Required Superpowers |
134
+ |-------|---------|---------------------|
135
+ | `[BASIT]` | Small fix, single file | verification |
136
+ | `[ORTA]` | Multiple files, moderate | brainstorming + TDD + verification |
137
+ | `[BUYUK]` | Architectural impact | brainstorming + plan + TDD + verification |
138
+
139
+ ### Plugin Distribution
140
+
141
+ Lead assigns plugins to workers based on project stack:
142
+
143
+ | Plugin | Frontend | Backend | QA | DevOps |
144
+ |--------|:--------:|:-------:|:--:|:------:|
145
+ | superpowers | required | required | required | required |
146
+ | typescript-lsp | yes | yes | - | - |
147
+ | chrome-devtools-mcp | yes | - | yes | - |
148
+ | frontend-design | yes | - | - | - |
149
+ | context7 | yes | yes | - | - |
150
+ | commit-commands | yes | yes | - | yes |
151
+ | security-guidance | - | yes | yes | yes |
152
+
153
+ ## Issue Pipeline
154
+
155
+ Every issue flows through a tracked pipeline:
156
+
157
+ ```
158
+ assigned → in_progress → dev_done → testing → qa_passed → done
159
+ → qa_rejected (back to dev)
160
+ ```
161
+
162
+ Pipeline state is synced across all peers via P2P. Late joiners receive full state on connect.
163
+
164
+ ## Network Requirements
165
+
166
+ - All machines must be on the **same local network** (LAN, Wi-Fi, or VPN)
167
+ - UDP multicast port `11776` must be reachable
168
+ - WebSocket port (auto-selected in range `11700-11750`) must be accessible
169
+
170
+ On Windows, allow network access when prompted on first run.
171
+
172
+ ## Configuration
173
+
174
+ | Env variable | Default | Description |
175
+ |---|---|---|
176
+ | `CLAUDE_COLLAB_PORT_MIN` | `11700` | WS port range start |
177
+ | `CLAUDE_COLLAB_PORT_MAX` | `11750` | WS port range end |
178
+ | `CLAUDE_COLLAB_LOG_DIR` | `~/.claude-collab/logs` | Override log file directory |
179
+
180
+ ## Architecture
181
+
182
+ ```
183
+ src/
184
+ ├── domain/ # Entities, Value Objects
185
+ ├── application/ # Use Cases, DTOs
186
+ ├── infrastructure/
187
+ │ ├── p2p/
188
+ │ │ ├── multicast-discovery.ts # UDP multicast peer discovery + auto-reconnect
189
+ │ │ ├── p2p-node.ts # WebSocket P2P node + ICollabClient + safeSend
190
+ │ │ ├── p2p-message-protocol.ts # Wire protocol (17 message types)
191
+ │ │ └── dashboard-broadcaster.ts # Real-time dashboard WebSocket
192
+ │ ├── logging/
193
+ │ │ └── collab-logger.ts # CollabLogger + logCrash
194
+ │ └── terminal-injector/
195
+ │ ├── windows-injector.ts # PowerShell P/Invoke (WriteConsoleInput)
196
+ │ ├── windows-reader.ts # ReadConsoleOutput
197
+ │ └── injection-queue.ts # FIFO message delivery + fire-and-forget
198
+ ├── shared/types/
199
+ │ └── collab-client.interface.ts # ICollabClient contract
200
+ ├── presentation/mcp/
201
+ │ ├── server.ts # MCP server setup
202
+ │ └── tools/ # 15 MCP tools
203
+ └── skills/ # 6 role-based skills
204
+ ```
205
+
206
+ ## P2P Message Types (17)
207
+
208
+ | Type | Purpose |
209
+ |------|---------|
210
+ | `P2P_HELLO` | Identity handshake on connect |
211
+ | `P2P_ASK` / `P2P_ASK_ACK` | Send question + acknowledge |
212
+ | `P2P_GET_ANSWER` / `P2P_ANSWER` | Check/deliver answer |
213
+ | `P2P_ANSWER_PENDING` | Answer not ready yet |
214
+ | `P2P_SEND` | Non-blocking message (fire-and-forget or expect-reply) |
215
+ | `P2P_OBSERVE_REQ` / `P2P_OBSERVE_RES` | Terminal observation |
216
+ | `P2P_BROADCAST` | Team-wide announcement |
217
+ | `P2P_STATUS_UPDATE` | Status reporting |
218
+ | `P2P_ISSUE_UPDATE` | Pipeline state change |
219
+ | `P2P_ISSUE_SYNC_REQ` / `P2P_ISSUE_SYNC_RES` | Pipeline state sync for late joiners |
220
+ | `P2P_PING` / `P2P_PONG` | Connection keepalive |
221
+ | `P2P_ERROR` | Error notification |
222
+
223
+ ## Logging
224
+
225
+ Claude Collab includes a structured logging system for debugging and observability.
226
+
227
+ - **`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.)
228
+ - **`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.
229
+ - **`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`.
230
+ - **Log files**: `~/.claude-collab/logs/` directory, daily rotation (date-based filenames), JSON-per-line format
231
+ - **Env variable**: `CLAUDE_COLLAB_LOG_DIR` overrides the log directory
232
+
233
+ ## Development
234
+
235
+ ```bash
236
+ git clone https://github.com/dolusoft/claude-collab.git
237
+ cd claude-collab
238
+ pnpm install
239
+ pnpm build # build with tsup
240
+ pnpm test # run tests
241
+ pnpm dev # watch mode
242
+ ```
243
+
244
+ ## License
245
+
246
+ MIT — see [LICENSE](LICENSE) for details.
247
+
248
+ ---
249
+
250
+ Created by [Dolusoft](https://github.com/dolusoft) · Built with [Model Context Protocol](https://modelcontextprotocol.io)