@dolusoft/claude-collab 1.11.0 → 1.11.2

package/README.md

@@ -7,12 +7,16 @@ Real-time collaboration between Claude Code terminals via MCP (Model Context Pro
 
 ## Overview
 
-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.
+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.
 
 ```
 alice ◄──────────────────► bob
-       direct WebSocket
-       (auto-discovered)
+         direct WebSocket
+         (manual IP connect)
+              │
+              ▼
+            carol
+   (auto-connected via mesh)
 ```
 
 ## Setup
@@ -27,28 +31,33 @@ 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`) |
 
-### Step 2 — Connect to peers
+### Step 2 — Find your IP
 
-Call `peer_find` in Claude Code:
+Call `status()` in Claude Code:
 
 ```
-peer_find()
+status()
 ```
 
-This will:
-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
+This shows your LAN IP address. Share it with your teammate.
 
-Everyone on the team should call `peer_find` at the same time when setting up.
+### Step 3 — Connect to a peer
 
-### Step 3 — Adding a new peer later
+Your teammate calls `connect()` with your IP:
 
-Only the **new peer** needs to call `peer_find`. Existing peers will connect to them automatically — no action needed from others.
+```
+connect("192.168.1.5")
+```
+
+On the **first call only**, a Windows UAC popup appears — click **Yes** to open port 12345 on your firewall. This stays open permanently.
+
+### Step 4 — Full mesh forms automatically
 
-### Step 4 — After a disconnect or restart
+If Alice is already connected to Bob, and Carol connects to Alice — Carol automatically connects to Bob as well. No extra steps needed.
 
-The disconnecting peer calls `peer_find` again. Others reconnect automatically.
+### Step 5 — After a disconnect or restart
+
+The disconnecting peer calls `connect(ip)` again to rejoin. Others do not need to do anything.
 
 ---
 
@@ -56,22 +65,30 @@ The disconnecting peer calls `peer_find` again. Others reconnect automatically.
 
 | Tool | Description |
 |------|-------------|
-| `peer_find` | Discover and connect to peers. Opens firewall, waits 30s, closes firewall. |
+| `connect` | Connect to a peer by their LAN IP. Opens firewall on first use (UAC popup). |
+| `status` | Show your name, LAN IP, port, and connected peers. |
 | `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
 
 ```
-# Alice asks Bob
-ask("bob", "What's the response format for the /users endpoint?")
+# Alice checks her IP and shares it with Bob
+status()
+# → Name: alice  IP: 192.168.1.5  Port: 12345
+
+# Bob connects to Alice
+connect("192.168.1.5")
+# → Connected to "alice". Use status() to see all connected peers.
 
-# Bob sees the question injected into his terminal and replies
+# Bob asks Alice a question
+ask("alice", "What's the response format for the /users endpoint?")
+
+# Alice sees the question injected into her terminal and replies
 reply("<question-id>", "Returns JSON: { id, name, email }")
 
-# Alice receives the answer
+# Bob receives the answer
 ```
 
 ## Use Case: Sharing Context Between Agents
@@ -106,19 +123,13 @@ sequenceDiagram
     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
+    Alice Claude Code->>Alice Claude Code: status()
+    Note over Alice Claude Code: IP: 192.168.1.5
 
-    Note over Alice Claude Code: firewall closes (connection persists)
-    Note over Bob Claude Code: firewall closes (connection persists)
+    Bob Claude Code->>Alice Claude Code: connect("192.168.1.5")
+    Note over Bob Claude Code: UAC popup → firewall opens (once)
+    Alice Claude Code-->>Bob Claude Code: HELLO_ACK
+    Note over Alice Claude Code,Bob Claude Code: Direct connection established
 
     User->>Alice Claude Code: "My API key is sk-abc123..."
     Note over Alice Claude Code: Stored in context
@@ -136,25 +147,24 @@ sequenceDiagram
 
 ```
 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
+  Each node binds a WebSocket server on fixed port 12345
+  If the port is already in use, the existing process is killed automatically
 
-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
+Connecting:
+  connect("IP") → opens firewall (first time only, UAC popup) → WebSocket handshake
+  After handshake: both sides exchange PEER_LIST
+  Each side connects to any unknown peers in the list (full mesh)
+  Existing peers are notified via PEER_ANNOUNCE and connect directly too
 
-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
+Questions:
+  ask() → sends ASK to peer → peer gets question injected into their terminal
+  reply() → sends ANSWER back → ask() call unblocks immediately (push, no polling)
 ```
 
 ## 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.
+- **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.).
 - **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.
@@ -187,26 +197,24 @@ node dist/mcp-main.js --name alice
 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.
+Then in terminal 2, call `connect("127.0.0.1")` — both nodes will connect on port 12345.
 
 ### Project structure
 
 ```
 src/
 ├── infrastructure/
-│   ├── discovery/
-│   │   └── multicast-discovery.ts  # UDP multicast (239.255.42.42:11776) + unicast reply
+│   ├── mesh/
+│   │   ├── mesh-node.ts    # WS server + client + peer management + mesh logic
+│   │   └── protocol.ts     # Wire protocol: HELLO, PEER_LIST, PEER_ANNOUNCE, ASK, ANSWER
 │   ├── 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
+│   │   └── firewall.ts     # Windows Firewall via UAC-elevated netsh
 │   └── terminal-injector/
-│       └── windows-injector.ts     # Injects questions into Claude Code via WriteConsoleInput
+│       └── windows-injector.ts  # Injects questions into Claude Code via WriteConsoleInput
 └── presentation/
     └── mcp/
-        ├── server.ts               # MCP server setup
-        └── tools/                  # ask, reply, peers, history, peer_find
+        ├── server.ts        # MCP server setup
+        └── tools/           # connect, status, ask, reply, history
 ```
 
 ## License

package/dist/cli.js

@@ -3,7 +3,7 @@ import { Command } from 'commander';
 import { WebSocket, WebSocketServer } from 'ws';
 import { v4 } from 'uuid';
 import os, { tmpdir } from 'os';
-import { spawn, execFile } from 'child_process';
+import { execSync, spawn, execFile } from 'child_process';
 import { EventEmitter } from 'events';
 import { unlinkSync } from 'fs';
 import { join } from 'path';
@@ -11,7 +11,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 
-// src/infrastructure/p2p/p2p-protocol.ts
+// src/infrastructure/mesh/protocol.ts
 function serialize(msg) {
   return JSON.stringify(msg);
 }
@@ -263,9 +263,9 @@ var InjectionQueue = class extends EventEmitter {
 };
 var injectionQueue = new InjectionQueue();
 
-// src/infrastructure/p2p/p2p-node.ts
+// src/infrastructure/mesh/mesh-node.ts
 var FIXED_PORT = 12345;
-var P2PNode = class {
+var MeshNode = class {
   server = null;
   myName = "";
   running = false;
@@ -352,7 +352,7 @@ var P2PNode = class {
           this.wsToName.delete(ws);
           if (this.peerConnections.get(name) === ws) {
             this.peerConnections.delete(name);
-            console.error(`[p2p] disconnected from peer: ${name}`);
+            console.error(`[mesh] disconnected from peer: ${name}`);
           }
         }
       });
@@ -366,7 +366,7 @@ var P2PNode = class {
   async ask(toPeer, content, format) {
     const ws = this.peerConnections.get(toPeer);
     if (!ws || ws.readyState !== WebSocket.OPEN) {
-      throw new Error(`Peer "${toPeer}" is not connected. Use peers() to see who's online.`);
+      throw new Error(`Peer "${toPeer}" is not connected. Use status() to see who's online.`);
     }
     const questionId = v4();
     this.sentQuestions.set(questionId, { toPeer, content, askedAt: (/* @__PURE__ */ new Date()).toISOString() });
@@ -426,7 +426,7 @@ var P2PNode = class {
         this.sendToWs(ws, answerMsg);
       } else {
         this.pendingOutboundAnswers.set(senderName, answerMsg);
-        console.error(`[p2p] "${senderName}" is offline, answer queued for delivery on reconnect`);
+        console.error(`[mesh] "${senderName}" is offline, answer queued for delivery on reconnect`);
       }
     }
     injectionQueue.notifyReplied();
@@ -500,13 +500,27 @@ var P2PNode = class {
   // ---------------------------------------------------------------------------
   // Private: server startup
   // ---------------------------------------------------------------------------
-  startServer() {
+  async startServer() {
+    try {
+      await this.tryBind();
+    } catch (err) {
+      const nodeErr = err;
+      if (nodeErr.code === "EADDRINUSE") {
+        console.error(`[mesh] port ${FIXED_PORT} in use \u2014 killing existing process`);
+        await killProcessOnPort(FIXED_PORT);
+        await this.tryBind();
+      } else {
+        throw err;
+      }
+    }
+  }
+  tryBind() {
     return new Promise((resolve, reject) => {
       const wss = new WebSocketServer({ port: FIXED_PORT });
       wss.once("listening", () => {
         this.server = wss;
         this.running = true;
-        console.error(`[p2p] listening on port ${FIXED_PORT} as "${this.myName}"`);
+        console.error(`[mesh] listening on port ${FIXED_PORT} as "${this.myName}"`);
         this.attachServerHandlers(wss);
         resolve();
       });
@@ -532,16 +546,16 @@ var P2PNode = class {
           this.wsToName.delete(ws);
           if (this.peerConnections.get(name) === ws) {
             this.peerConnections.delete(name);
-            console.error(`[p2p] peer disconnected (inbound): ${name}`);
+            console.error(`[mesh] peer disconnected (inbound): ${name}`);
           }
         }
       });
       ws.on("error", (err) => {
-        console.error("[p2p] inbound ws error:", err.message);
+        console.error("[mesh] inbound ws error:", err.message);
       });
     });
     wss.on("error", (err) => {
-      console.error("[p2p] server error:", err.message);
+      console.error("[mesh] server error:", err.message);
     });
   }
   // ---------------------------------------------------------------------------
@@ -565,7 +579,7 @@ var P2PNode = class {
     this.wsToName.set(ws, name);
     this.peerIPs.set(name, ip);
     this.connectingPeers.delete(name);
-    console.error(`[p2p] peer registered: ${name} @ ${ip}`);
+    console.error(`[mesh] peer registered: ${name} @ ${ip}`);
     this.deliverPendingAnswer(name, ws);
   }
   /** Connect outbound to a peer discovered via PEER_LIST or PEER_ANNOUNCE. */
@@ -590,12 +604,12 @@ var P2PNode = class {
         this.wsToName.delete(ws);
         if (this.peerConnections.get(peerName) === ws) {
           this.peerConnections.delete(peerName);
-          console.error(`[p2p] disconnected from mesh peer: ${peerName}`);
+          console.error(`[mesh] disconnected from mesh peer: ${peerName}`);
         }
       }
     });
     ws.on("error", (err) => {
-      console.error(`[p2p] mesh connect to "${name}" @ ${ip} failed: ${err.message}`);
+      console.error(`[mesh] connect to "${name}" @ ${ip} failed: ${err.message}`);
       this.connectingPeers.delete(name);
     });
   }
@@ -612,7 +626,7 @@ var P2PNode = class {
       }
       this.registerPeer(msg.name, remoteIp, ws);
       this.sendToWs(ws, { type: "HELLO_ACK", name: this.myName });
-      console.error(`[p2p] peer joined (inbound): ${msg.name}`);
+      console.error(`[mesh] peer joined (inbound): ${msg.name}`);
       this.afterHandshake(msg.name, ws);
       return;
     }
@@ -627,7 +641,7 @@ var P2PNode = class {
           this.peerConnections.set(msg.name, ws);
           this.wsToName.set(ws, msg.name);
           this.connectingPeers.delete(msg.name);
-          console.error(`[p2p] connected to mesh peer: ${msg.name}`);
+          console.error(`[mesh] connected to mesh peer: ${msg.name}`);
           this.deliverPendingAnswer(msg.name, ws);
           this.afterHandshake(msg.name, ws);
         }
@@ -635,7 +649,7 @@ var P2PNode = class {
       case "PEER_LIST":
         for (const peer of msg.peers) {
           if (peer.name !== this.myName && !this.peerConnections.has(peer.name)) {
-            console.error(`[p2p] mesh: connecting to ${peer.name} @ ${peer.ip} via PEER_LIST`);
+            console.error(`[mesh] connecting to ${peer.name} @ ${peer.ip} via PEER_LIST`);
             this.peerIPs.set(peer.name, peer.ip);
             this.connectMeshPeer(peer.name, peer.ip);
           }
@@ -643,7 +657,7 @@ var P2PNode = class {
         break;
       case "PEER_ANNOUNCE":
         if (msg.name !== this.myName && !this.peerConnections.has(msg.name)) {
-          console.error(`[p2p] mesh: connecting to ${msg.name} @ ${msg.ip} via PEER_ANNOUNCE`);
+          console.error(`[mesh] connecting to ${msg.name} @ ${msg.ip} via PEER_ANNOUNCE`);
           this.peerIPs.set(msg.name, msg.ip);
           this.connectMeshPeer(msg.name, msg.ip);
         }
@@ -695,7 +709,7 @@ var P2PNode = class {
     if (pending) {
       this.pendingOutboundAnswers.delete(peerName);
       this.sendToWs(ws, pending);
-      console.error(`[p2p] delivered queued answer to "${peerName}" after reconnect`);
+      console.error(`[mesh] delivered queued answer to "${peerName}" after reconnect`);
     }
   }
   sendToWs(ws, msg) {
@@ -720,6 +734,34 @@ var P2PNode = class {
     });
   }
 };
+async function killProcessOnPort(port) {
+  try {
+    if (process.platform === "win32") {
+      const out = execSync(
+        `netstat -ano | findstr ":${port} "`,
+        { encoding: "utf8", stdio: ["pipe", "pipe", "ignore"] }
+      );
+      const pids = /* @__PURE__ */ new Set();
+      for (const line of out.split("\n")) {
+        const parts = line.trim().split(/\s+/);
+        if (parts.length >= 5 && parts[3] === "LISTENING" && parts[4]) {
+          pids.add(parts[4]);
+        }
+      }
+      for (const pid of pids) {
+        try {
+          execSync(`taskkill /PID ${pid} /F`, { stdio: "ignore" });
+          console.error(`[mesh] killed PID ${pid} on port ${port}`);
+        } catch {
+        }
+      }
+    } else {
+      execSync(`fuser -k ${port}/tcp`, { stdio: "ignore" });
+    }
+  } catch {
+  }
+  await new Promise((resolve) => setTimeout(resolve, 300));
+}
 var CONNECT_DESCRIPTION = `Connect to another Claude instance by their IP address.
 
 WHEN TO USE:
@@ -822,7 +864,7 @@ function registerAskTool(server, client) {
         return {
           content: [{
             type: "text",
-            text: "P2P node is not ready yet. Wait a moment and try again."
+            text: "Node is not ready yet. Wait a moment and try again."
           }],
           isError: true
         };
@@ -903,7 +945,7 @@ function registerReplyTool(server, client) {
         return {
           content: [{
             type: "text",
-            text: "P2P node is not ready yet. Wait a moment and try again."
+            text: "Node is not ready yet. Wait a moment and try again."
           }],
           isError: true
         };
@@ -930,68 +972,6 @@ function registerReplyTool(server, client) {
   });
 }
 
-// src/presentation/mcp/tools/peers.tool.ts
-var PEERS_DESCRIPTION = `List all currently active peer connections.
-
-WHEN TO USE:
-- Before calling ask() \u2014 to confirm the target peer is online and get their exact name
-- After connect() \u2014 to verify the connection succeeded and the mesh formed
-- When a peer seems unreachable \u2014 to check if they are still connected
-
-WHAT IT SHOWS:
-- Your own name and port
-- All peers with an active direct connection
-
-IF NO PEERS ARE LISTED:
-- Use connect(ip) to connect to a peer
-- Ask your teammate to run status() to get their IP`;
-function registerPeersTool(server, client) {
-  server.tool("peers", PEERS_DESCRIPTION, {}, async () => {
-    const info = client.getInfo();
-    const myName = info.teamName ?? "(starting...)";
-    const myPort = info.port ?? "?";
-    const connected = info.connectedPeers;
-    if (!client.isConnected) {
-      return {
-        content: [{
-          type: "text",
-          text: [
-            `P2P server is not running yet (port ${myPort} may be in use).`,
-            `Check the MCP process logs for the error details.`
-          ].join("\n")
-        }],
-        isError: true
-      };
-    }
-    if (connected.length === 0) {
-      return {
-        content: [{
-          type: "text",
-          text: [
-            `You are "${myName}" (listening on port ${myPort}).`,
-            `No peers connected yet.`,
-            ``,
-            `Use connect(ip) to connect to a peer.`,
-            `Ask your teammate to run status() to get their IP.`
-          ].join("\n")
-        }]
-      };
-    }
-    const peerIPs = info.peerIPs ?? {};
-    const list = connected.map((name) => {
-      const ip = peerIPs[name] ? ` (${peerIPs[name]})` : "";
-      return `  \u2022 ${name}${ip}`;
-    }).join("\n");
-    return {
-      content: [{
-        type: "text",
-        text: `You are "${myName}" (port ${myPort}). Connected peers (${connected.length}):
-${list}`
-      }]
-    };
-  });
-}
-
 // src/presentation/mcp/tools/history.tool.ts
 var HISTORY_DESCRIPTION = `Show all questions and answers exchanged this session \u2014 both sent and received.
 
@@ -1060,12 +1040,23 @@ function registerStatusTool(server, client) {
       };
     }
     let ips = [];
-    if (client instanceof P2PNode) {
+    if (client instanceof MeshNode) {
       ips = client.getLocalIps();
     }
     const ipLine = ips.length > 0 ? ips.join(", ") : "(could not detect \u2014 check your network interface)";
-    const peerCount = info.connectedPeers.length;
-    const peerLine = peerCount === 0 ? "No peers connected yet. Share your IP so others can connect(ip)." : `Connected to ${peerCount} peer(s): ${info.connectedPeers.map((n) => `"${n}"`).join(", ")}`;
+    const peerIPs = info.peerIPs ?? {};
+    const connected = info.connectedPeers;
+    let peersSection;
+    if (connected.length === 0) {
+      peersSection = "No peers connected yet. Share your IP so others can connect(ip).";
+    } else {
+      const list = connected.map((n) => {
+        const ip = peerIPs[n] ? ` (${peerIPs[n]})` : "";
+        return `  \u2022 ${n}${ip}`;
+      }).join("\n");
+      peersSection = `Connected peers (${connected.length}):
+${list}`;
+    }
     return {
       content: [{
         type: "text",
@@ -1074,7 +1065,7 @@ function registerStatusTool(server, client) {
           `IP:    ${ipLine}`,
           `Port:  ${port}`,
           ``,
-          peerLine
+          peersSection
         ].join("\n")
       }]
     };
@@ -1092,7 +1083,6 @@ function createMcpServer(options) {
   registerStatusTool(server, client);
   registerAskTool(server, client);
   registerReplyTool(server, client);
-  registerPeersTool(server, client);
   registerHistoryTool(server, client);
   return server;
 }
@@ -1105,7 +1095,7 @@ async function startMcpServer(options) {
 // src/cli.ts
 var program = new Command();
 program.name("claude-collab").description("Collaboration between Claude Code terminals via MCP").version("0.1.0").requiredOption("--name <name>", 'Your name on the network (e.g. "alice")').action(async (options) => {
-  const node = new P2PNode();
+  const node = new MeshNode();
   const mcpReady = startMcpServer({ client: node });
   node.join(options.name, options.name).catch((err) => {
     console.error(`[cli] Failed to start on port 12345: ${err.message}`);