@dolusoft/claude-collab 1.10.3 → 1.10.4

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,10 +68,29 @@ 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 sees the answer
+# Alice receives the answer
+```
+
+## 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
 ```
 
 ## Architecture
@@ -96,17 +98,16 @@ reply("q_abc123", "Returns JSON: { id, name, email }")
 ```
 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
+│   ├── 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 (start_hub, stop_hub, ask, reply, peers, history)
+    └── mcp/                        # MCP server + tools
 ```
 
 ## Development

package/dist/cli.js

@@ -1044,128 +1044,7 @@ async function removeFirewallRule(port) {
   }
 }
 
-// src/presentation/mcp/tools/firewall-open.tool.ts
-var FIREWALL_OPEN_DESCRIPTION = `Open a Windows Firewall inbound rule so peers on the LAN can connect directly to you.
-
-WHEN YOU NEED THIS:
-- Other peers cannot see you in their peers() list even though you are on the same LAN
-- You just started and want to make sure all peers can reach you
-- A peer explicitly says they cannot connect to you
-
-WHEN YOU DO NOT NEED THIS:
-- You can already see peers in peers() \u2014 the connection is working
-- You are connecting outbound to others (outbound connections do not require firewall rules)
-
-WHAT HAPPENS:
-- On most systems: the rule is applied immediately (terminal is already elevated)
-- On standard Windows: a UAC popup appears \u2014 the user must click Yes
-- On VMs or headless setups: applied directly if running as Administrator
-
-The rule is named "claude-collab-{port}" and allows inbound TCP on your current listen port.
-Call firewall_close() when you are done to clean up the rule.`;
-function registerFirewallOpenTool(server, client) {
-  server.tool(
-    "firewall_open",
-    FIREWALL_OPEN_DESCRIPTION,
-    {
-      port: z.number().min(1024).max(65535).optional().describe(
-        "Port to open. Defaults to your current listen port \u2014 omit this unless you have a specific reason to override."
-      )
-    },
-    async ({ port }) => {
-      const targetPort = port ?? client.getInfo().port;
-      if (!targetPort) {
-        return {
-          content: [{ type: "text", text: "P2P node is not running yet \u2014 port unknown. Try again in a moment." }],
-          isError: true
-        };
-      }
-      try {
-        await addFirewallRule(targetPort);
-        return {
-          content: [{
-            type: "text",
-            text: [
-              `Firewall rule opened for port ${targetPort} (claude-collab-${targetPort}).`,
-              `Peers on the LAN can now connect to you inbound.`,
-              `Call firewall_close() when you are done with this session.`
-            ].join("\n")
-          }]
-        };
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-          content: [{
-            type: "text",
-            text: [
-              `Failed to open firewall: ${msg}`,
-              ``,
-              `Try running your terminal as Administrator and call firewall_open() again.`
-            ].join("\n")
-          }],
-          isError: true
-        };
-      }
-    }
-  );
-}
-var FIREWALL_CLOSE_DESCRIPTION = `Remove the Windows Firewall inbound rule that was opened by firewall_open().
-
-WHEN TO USE:
-- At the end of a collaboration session to clean up
-- When you no longer want to accept inbound peer connections
-- As general hygiene \u2014 open firewall rules should not be left indefinitely
-
-WHAT HAPPENS:
-- The inbound TCP rule "claude-collab-{port}" is deleted from Windows Firewall
-- Existing active connections are not dropped \u2014 only new inbound connections are blocked
-- On standard Windows: a UAC popup appears \u2014 the user must click Yes
-- On VMs or admin terminals: applied directly without a popup
-
-NOTE: Because ports are random each session, each startup creates a new rule name.
-Old rules from previous sessions can be removed by passing the port explicitly.`;
-function registerFirewallCloseTool(server, client) {
-  server.tool(
-    "firewall_close",
-    FIREWALL_CLOSE_DESCRIPTION,
-    {
-      port: z.number().min(1024).max(65535).optional().describe(
-        "Port whose rule to remove. Defaults to your current listen port. Pass a specific port to clean up a rule from a previous session."
-      )
-    },
-    async ({ port }) => {
-      const targetPort = port ?? client.getInfo().port;
-      if (!targetPort) {
-        return {
-          content: [{ type: "text", text: "P2P node is not running yet \u2014 port unknown. Try again in a moment." }],
-          isError: true
-        };
-      }
-      try {
-        await removeFirewallRule(targetPort);
-        return {
-          content: [{
-            type: "text",
-            text: `Firewall rule removed for port ${targetPort} (claude-collab-${targetPort}).`
-          }]
-        };
-      } catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-          content: [{
-            type: "text",
-            text: [
-              `Failed to remove firewall rule: ${msg}`,
-              ``,
-              `The rule may not exist (if firewall_open was never called this session), or try running as Administrator.`
-            ].join("\n")
-          }],
-          isError: true
-        };
-      }
-    }
-  );
-}
+// src/presentation/mcp/tools/peer-find.tool.ts
 var PEER_FIND_DESCRIPTION = `Discover and connect to peers on the LAN automatically.
 
 WHAT IT DOES:
@@ -1256,8 +1135,6 @@ function createMcpServer(options) {
   registerReplyTool(server, client);
   registerPeersTool(server, client);
   registerHistoryTool(server, client);
-  registerFirewallOpenTool(server, client);
-  registerFirewallCloseTool(server, client);
   registerPeerFindTool(server, client);
   return server;
 }