@dolusoft/claude-collab 1.5.0 → 1.6.0

package/README.md

@@ -1,133 +1,88 @@
 # Claude Collab
 
-Real-time P2P collaboration between Claude Code terminals via MCP (Model Context Protocol).
+Real-time collaboration between Claude Code terminals via MCP (Model Context Protocol).
 
 [![npm version](https://badge.fury.io/js/@dolusoft%2Fclaude-collab.svg)](https://www.npmjs.com/package/@dolusoft/claude-collab)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ## Overview
 
-Claude Collab lets multiple Claude Code terminals communicate with each other 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.
+Claude Collab lets multiple Claude Code terminals communicate with each other in real-time. One machine runs a lightweight hub server; everyone else connects to it — no firewall rules needed for clients.
 
 ```
-┌──────────────────┐        ┌──────────────────┐        ┌──────────────────┐
-│  alice           │◄──────►│  bob             │◄──────►│  charlie         │
-│  Claude Code     │        │  Claude Code     │        │  Claude Code     │
-└──────────────────┘        └──────────────────┘        └──────────────────┘
-         auto-discovered via UDP multicast (239.255.42.42)
+alice ──outbound──→ ┌─────────────────┐ ←──outbound── bob
+charlie─outbound──→ │   hub server    │ ←──outbound── dave
+                    │ 192.168.1.5:9999│
+                    └─────────────────┘
 ```
 
-## How It Works
+## Setup
 
-- Each terminal joins a shared **multicast group** on the LAN (like a meeting table)
-- When a terminal comes online it announces itself; others discover it automatically
-- Direct WebSocket connections are established between peers — no central server
-- When a terminal goes offline, peers detect it and remove it from the list
+### Step 1 — Start the hub (one machine, one time)
 
-## Installation
-
-### Option 1 — Without global install (recommended)
+Pick any machine on your network. Run in a terminal:
 
 ```bash
-claude mcp add claude-collab -- npx -y @dolusoft/claude-collab --name alice
+npx @dolusoft/claude-collab --hub --port 9999
 ```
 
-Replace `alice` with your chosen name. That's it — run this once per machine.
+Keep this terminal open. The hub routes messages between everyone.
 
-### Option 2 — With global install
+### Step 2 — Add to Claude Code (each machine, one time)
 
 ```bash
-npm install -g @dolusoft/claude-collab
-claude mcp add claude-collab -- claude-collab --name alice
+claude mcp add claude-collab -- npx -y @dolusoft/claude-collab --name alice --server 192.168.1.5:9999
 ```
 
-> **Your name is saved permanently** in Claude Code's MCP config. Every time Claude Code opens, it starts as `alice` automatically — you never need to set it again.
+Replace `alice` with your name and `192.168.1.5:9999` with the hub machine's IP and port.
 
-## Quick Start
+> Your name and server address are saved permanently in Claude Code's MCP config. Every time Claude Code opens, it connects automatically — you never need to reconfigure.
 
-**Machine 1 (Alice):**
-```bash
-claude mcp add claude-collab -- npx -y @dolusoft/claude-collab --name alice
-```
+### With global install
 
-**Machine 2 (Bob):**
 ```bash
-claude mcp add claude-collab -- npx -y @dolusoft/claude-collab --name bob
-```
-
-Open Claude Code on both machines. Within ~30 seconds they find each other automatically. Then just use the tools:
-
-```
-# Ask bob a question (alice's terminal)
-ask("bob", "What's the API response format for /users?")
+npm install -g @dolusoft/claude-collab
 
-# Check inbox for incoming questions
-inbox()
+# Hub:
+claude-collab --hub --port 9999
 
-# Reply to a question
-reply("q_abc123", "It returns JSON: {id, name, email}")
+# Client (add to Claude Code):
+claude mcp add claude-collab -- claude-collab --name alice --server 192.168.1.5:9999
 ```
 
 ## MCP Tools
 
 | Tool | Description |
 |------|-------------|
-| `ask` | Ask a peer a question. Waits up to 5 minutes for a response. |
-| `inbox` | List questions waiting for your reply. |
-| `reply` | Reply to a question by its ID. |
-| `check_answer` | Manually check if an answer arrived for a question ID. |
-| `get_info` | Show your name, port, local IPs, and connected peers. |
-
-## Use Cases
+| `ask` | Ask another peer a question. Waits up to 5 minutes for a response. |
+| `reply` | Reply to an incoming question (called automatically by Claude). |
+| `peers` | Show currently connected peers. |
+| `history` | Show past questions and answers from this session. |
 
-### Bug Coordination
+## Example
 
 ```
-alice: ask("bob", "We're seeing duplicate SignalR messages — can you check if
-       OnConnectedAsync is being called multiple times on your side?")
+# Alice asks Bob
+ask("bob", "What's the response format for the /users endpoint?")
 
-bob: reply("q_abc", "Found it. Logs show 2 connection IDs for the same user —
-     React StrictMode is causing double connections.")
-```
-
-### API Design Sync
+# Bob sees the question automatically and replies
+reply("q_abc123", "Returns JSON: { id, name, email }")
 
+# Alice sees the answer
 ```
-alice: ask("bob", "What should the request payload look like for checkout?")
-
-bob: reply("q_xyz", "Here's the schema:
-     { items: [{id: string, quantity: number}], paymentMethod: 'card' | 'paypal' }")
-```
-
-## Network Requirements
-
-- All machines must be on the **same local network** (LAN, office Wi-Fi, home network, or VPN)
-- UDP multicast port `11776` must be reachable within the subnet (not blocked between peers)
-- WebSocket port (auto-selected in range `11700–11750`) needs to be accessible on the local network
-
-On first run, Windows will ask "Allow this app on the network?" — click **Allow**. This is a one-time prompt per machine.
-
-## Configuration
-
-| Env variable | Default | Description |
-|---|---|---|
-| `CLAUDE_COLLAB_PORT_MIN` | `11700` | WS port range start |
-| `CLAUDE_COLLAB_PORT_MAX` | `11750` | WS port range end |
 
 ## Architecture
 
 ```
 src/
-├── domain/           # Entities, Value Objects, Domain Events
-├── application/      # Use Cases, DTOs
 ├── infrastructure/
-│   ├── p2p/
-│   │   ├── multicast-discovery.ts   # UDP multicast peer discovery
-│   │   ├── p2p-node.ts              # WebSocket P2P node + ICollabClient
-│   │   └── p2p-message-protocol.ts  # Wire protocol types
-│   └── terminal-injector/           # Injects questions into Claude Code terminal
+│   ├── hub/
+│   │   ├── hub-server.ts     # WebSocket hub — routes messages by name
+│   │   ├── hub-client.ts     # Connects to hub, implements ICollabClient
+│   │   └── hub-protocol.ts   # Wire protocol types
+│   └── terminal-injector/    # Injects incoming questions into Claude Code
 └── presentation/
-    └── mcp/                         # MCP server + tools
+    └── mcp/                  # MCP server + tools
 ```
 
 ## Development
@@ -136,9 +91,8 @@ src/
 git clone https://github.com/dolusoft/claude-collab.git
 cd claude-collab
 pnpm install
-pnpm build    # build
-pnpm test     # run tests
-pnpm dev      # watch mode
+pnpm build
+pnpm test
 ```
 
 ## License