@dolusoft/claude-collab 1.10.4 → 1.11.0

package/README.md

@@ -74,6 +74,64 @@ 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.
+
+**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?")
+```
+
+Alice Claude Code's terminal receives the question, and she replies from what she already knows:
+
+```
+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
 
 ```
@@ -93,22 +151,18 @@ peer_find:
   connect outbound to them automatically
 ```
 
-## Architecture
+## Limitations
 
-```
-src/
-├── infrastructure/
-│   ├── discovery/
-│   │   └── multicast-discovery.ts  # UDP multicast + unicast reply
-│   ├── firewall/
-│   │   └── firewall.ts             # Windows Firewall via UAC (netsh)
-│   ├── p2p/
-│   │   ├── p2p-node.ts             # WS server + client + discovery
-│   │   └── p2p-protocol.ts         # Wire protocol (HELLO, ASK, ANSWER…)
-│   └── terminal-injector/          # Injects incoming questions into Claude Code
-└── presentation/
-    └── mcp/                        # MCP server + tools
-```
+- **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
 
@@ -116,8 +170,43 @@ src/
 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