@dolusoft/claude-collab 1.10.3 → 1.11.0

package/README.md

@@ -7,13 +7,12 @@ Real-time collaboration between Claude Code terminals via MCP (Model Context Pro
 
 ## Overview
 
-Claude Collab lets multiple Claude Code terminals communicate with each other in real-time. One machine starts a hub server via MCP tool — others on the same LAN auto-discover and connect via mDNS. No manual IP sharing, no terminal commands.
+Claude Collab lets multiple Claude Code terminals communicate directly — no central server needed. Each peer runs its own node; peers discover each other automatically on the LAN via UDP multicast and connect directly over WebSocket.
 
 ```
-alice ──outbound──→ ┌─────────────────┐ ←──outbound── bob
-charlie─outbound──→ │   hub server    │ ←──outbound── dave
-                    │ (auto-discover) │
-                    └─────────────────┘
+alice ◄──────────────────► bob
+       direct WebSocket
+       (auto-discovered)
 ```
 
 ## Setup
@@ -28,55 +27,39 @@ claude mcp add claude-collab -- npx -y @dolusoft/claude-collab --name <your-name
 |-------------|-------------|
 | `<your-name>` | Your identifier on the network (e.g. `alice`, `backend`, `frontend`) |
 
-> Your name is saved permanently in Claude Code's MCP config. No server address needed — the hub is discovered automatically on the LAN.
+### Step 2 — Connect to peers
 
-### Step 2 — One person starts the hub (via MCP tool)
-
-In Claude Code, call the `start_hub` tool:
+Call `peer_find` in Claude Code:
 
 ```
-start_hub()           # uses default port 9999
-start_hub(port=8888)  # custom port
+peer_find()
 ```
 
 This will:
-1. Start the hub server on your machine
-2. Show a **Windows UAC prompt** once — click **Yes** to open the firewall port
-3. Advertise the hub on your LAN via mDNS
-
-Everyone else will auto-connect within seconds. No IP address sharing needed.
+1. Open a **Windows UAC prompt** — click **Yes** to open your firewall
+2. Wait 30 seconds while peers are discovered and connected
+3. Close the firewall (another UAC prompt) — existing connections persist
 
-### Step 3 — Stop the hub when done
+Everyone on the team should call `peer_find` at the same time when setting up.
 
-```
-stop_hub()
-```
-
-This stops the server and removes the firewall rule (UAC prompt shown once).
-
----
+### Step 3 — Adding a new peer later
 
-### Manual / advanced mode
+Only the **new peer** needs to call `peer_find`. Existing peers will connect to them automatically — no action needed from others.
 
-If you prefer to manage the hub yourself (e.g. on a server), you can still use the legacy approach:
+### Step 4 — After a disconnect or restart
 
-```bash
-# Start hub manually in a terminal:
-npx @dolusoft/claude-collab --hub --port 9999
+The disconnecting peer calls `peer_find` again. Others reconnect automatically.
 
-# Add to Claude Code with explicit server address:
-claude mcp add claude-collab -- npx -y @dolusoft/claude-collab --name <your-name> --server <hub-ip>:<hub-port>
-```
+---
 
 ## MCP Tools
 
 | Tool | Description |
 |------|-------------|
-| `start_hub` | Start a hub server on this machine. Opens firewall via UAC, advertises on LAN via mDNS. |
-| `stop_hub` | Stop the running hub. Removes firewall rule via UAC. |
-| `ask` | Ask another peer a question by name. Waits up to 5 minutes for a response. |
-| `reply` | Reply to an incoming question (called automatically by Claude when a question arrives). |
-| `peers` | Show currently connected peers and your own name. |
+| `peer_find` | Discover and connect to peers. Opens firewall, waits 30s, closes firewall. |
+| `ask` | Ask a peer a question by name. Waits up to 5 minutes for a reply. |
+| `reply` | Reply to an incoming question. |
+| `peers` | Show connected peers and your own name/port. |
 | `history` | Show past questions and answers from this session. |
 
 ## Example
@@ -85,38 +68,145 @@ claude mcp add claude-collab -- npx -y @dolusoft/claude-collab --name <your-name
 # Alice asks Bob
 ask("bob", "What's the response format for the /users endpoint?")
 
-# Bob sees the question automatically and replies
-reply("q_abc123", "Returns JSON: { id, name, email }")
+# Bob sees the question injected into his terminal and replies
+reply("<question-id>", "Returns JSON: { id, name, email }")
+
+# Alice receives the answer
+```
+
+## Use Case: Sharing Context Between Agents
+
+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.
 
-# Alice sees the answer
+**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.
+
+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:
+
+> *"My API key is sk-abc123..."*
+
+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.
+
+Bob Claude Code asks Alice Claude Code directly:
+
+```
+ask("alice", "What is the API key?")
 ```
 
-## Architecture
+Alice Claude Code's terminal receives the question, and she replies from what she already knows:
 
 ```
-src/
-├── infrastructure/
-│   ├── hub/
-│   │   ├── hub-server.ts    # WebSocket hub — routes messages by name
-│   │   ├── hub-client.ts    # Connects to hub, implements ICollabClient
-│   │   ├── hub-manager.ts   # Orchestrates hub + firewall + mDNS advertising
-│   │   └── hub-protocol.ts  # Wire protocol types
-│   ├── mdns/
-│   │   ├── mdns-advertiser.ts  # Broadcasts hub presence on LAN via mDNS
-│   │   └── mdns-discovery.ts   # Discovers hub on LAN via mDNS
-│   └── terminal-injector/   # Injects incoming questions into Claude Code
-└── presentation/
-    └── mcp/                 # MCP server + tools (start_hub, stop_hub, ask, reply, peers, history)
+reply("<question-id>", "sk-abc123...")
 ```
 
+Bob Claude Code gets the answer and continues working — without the user having to repeat themselves.
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Alice Claude Code
+    participant Bob Claude Code
+
+    Alice Claude Code->>Alice Claude Code: peer_find()
+    Note over Alice Claude Code: UAC popup → firewall opens
+    Bob Claude Code->>Bob Claude Code: peer_find()
+    Note over Bob Claude Code: UAC popup → firewall opens
+
+    Alice Claude Code-)Bob Claude Code: UDP multicast discovery
+    Bob Claude Code-)Alice Claude Code: UDP multicast discovery
+    Alice Claude Code->>Bob Claude Code: WebSocket HELLO
+    Bob Claude Code-->>Alice Claude Code: HELLO_ACK
+    Note over Alice Claude Code,Bob Claude Code: P2P connection established
+
+    Note over Alice Claude Code: firewall closes (connection persists)
+    Note over Bob Claude Code: firewall closes (connection persists)
+
+    User->>Alice Claude Code: "My API key is sk-abc123..."
+    Note over Alice Claude Code: Stored in context
+
+    Bob Claude Code->>Alice Claude Code: ask("alice", "What is the API key?")
+    Alice Claude Code-->>Bob Claude Code: ASK_ACK
+    Note over Alice Claude Code: Question injected into terminal
+    Alice Claude Code->>Bob Claude Code: reply(questionId, "sk-abc123...")
+    Note over Bob Claude Code: Uses API key
+```
+
+---
+
+## How it works
+
+```
+Startup:
+  Each peer binds a WebSocket server on a random port (10000–19999)
+  Each peer broadcasts UDP multicast (239.255.42.42:11776) every 5s
+
+Discovery:
+  Peer A hears Peer B's multicast → connects outbound to B's WS port
+  If multicast is one-way (e.g. VMware + WiFi), the receiving side
+  sends a unicast reply so both peers discover each other
+
+peer_find:
+  Opens firewall (inbound TCP + UDP 11776) → wait → closes firewall
+  Established connections persist after firewall closes (stateful TCP)
+  New peers only need to open their own firewall — existing peers
+  connect outbound to them automatically
+```
+
+## Limitations
+
+- **Windows only** — terminal injection uses `kernel32.dll` Win32 APIs (`AttachConsole`, `WriteConsoleInput`) compiled via PowerShell. macOS and Linux are not supported.
+- **LAN only** — UDP multicast TTL is set to 1, so packets cannot cross routers. Does not work over the internet or VPNs that don't forward multicast.
+- **No encryption** — peer connections use plain `ws://` WebSocket. Traffic is unencrypted on the network.
+- **5-minute answer timeout** — if the peer does not reply within 5 minutes, `ask()` times out. The question is not retried automatically.
+- **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.
+- **No persistence** — all questions, answers, and history are stored in memory. Restarting the process clears everything.
+- **No broadcast** — `ask()` targets a single peer by name. There is no tool to send a message to all peers at once.
+- **Peer names are not unique** — if two peers join with the same name, the second connection is silently dropped.
+
+---
+
 ## Development
 
 ```bash
 git clone https://github.com/dolusoft/claude-collab.git
 cd claude-collab
 pnpm install
-pnpm build
-pnpm test
+pnpm build      # tsup → dist/mcp-main.js + dist/cli.js
+pnpm typecheck  # tsc --noEmit
+pnpm test       # vitest unit tests
+```
+
+### Testing locally with two peers
+
+Open two terminals on the same machine and run:
+
+```bash
+# Terminal 1
+node dist/mcp-main.js --name alice
+
+# Terminal 2
+node dist/mcp-main.js --name bob
+```
+
+Both nodes will bind on random ports in the `10000–19999` range and discover each other via UDP multicast automatically.
+
+### Project structure
+
+```
+src/
+├── infrastructure/
+│   ├── discovery/
+│   │   └── multicast-discovery.ts  # UDP multicast (239.255.42.42:11776) + unicast reply
+│   ├── firewall/
+│   │   └── firewall.ts             # Windows Firewall via UAC-elevated netsh
+│   ├── p2p/
+│   │   ├── p2p-node.ts             # WS server + client + peer management
+│   │   └── p2p-protocol.ts         # Wire protocol: HELLO, ASK, ASK_ACK, ANSWER
+│   └── terminal-injector/
+│       └── windows-injector.ts     # Injects questions into Claude Code via WriteConsoleInput
+└── presentation/
+    └── mcp/
+        ├── server.ts               # MCP server setup
+        └── tools/                  # ask, reply, peers, history, peer_find
 ```
 
 ## License