@dolusoft/claude-collab 1.4.3 → 1.5.0

package/README.md

@@ -1,236 +1,150 @@
 # Claude Collab
 
-Real-time team collaboration between Claude Code terminals via MCP (Model Context Protocol).
+Real-time P2P 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 enables multiple Claude Code terminals to communicate with each other in real-time. Perfect for teams where frontend and backend developers need their Claude Code instances to share context, ask questions, and coordinate on complex debugging sessions.
+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.
 
 ```
-┌─────────────────┐         ┌─────────────────┐
-│  Frontend       │◄───────►│  Backend        │
-│  Claude Code    │   Hub   │  Claude Code    │
-│  Terminal       │         │  Terminal       │
-└─────────────────┘         └─────────────────┘
+┌──────────────────┐        ┌──────────────────┐        ┌──────────────────┐
+│  alice           │◄──────►│  bob             │◄──────►│  charlie         │
+│  Claude Code     │        │  Claude Code     │        │  Claude Code     │
+└──────────────────┘        └──────────────────┘        └──────────────────┘
+         auto-discovered via UDP multicast (239.255.42.42)
 ```
 
-## Features
+## How It Works
 
-- **Real-time Communication**: Instant message exchange between Claude Code terminals
-- **Team Channels**: Organize communication by team (frontend, backend, devops, etc.)
-- **Question & Answer**: Ask questions to other teams and receive responses
-- **Markdown Support**: Share code snippets and formatted text
-- **Auto-Hub**: Hub server starts automatically when needed
-- **Zero Config**: Works out of the box with sensible defaults
+- 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
 
 ## Installation
 
-No cloning required! Install directly via npx:
+### Option 1 — Without global install (recommended)
 
 ```bash
-# Start the hub server
-npx @dolusoft/claude-collab hub start
-
-# Or add to Claude Code with auto-hub
-claude mcp add claude-collab -- npx @dolusoft/claude-collab client --team frontend --auto-hub
+claude mcp add claude-collab -- npx -y @dolusoft/claude-collab --name alice
 ```
 
-## Quick Start
+Replace `alice` with your chosen name. That's it — run this once per machine.
 
-### 1. Start the Hub (one-time setup)
+### Option 2 — With global install
 
 ```bash
-npx @dolusoft/claude-collab hub start
+npm install -g @dolusoft/claude-collab
+claude mcp add claude-collab -- claude-collab --name alice
 ```
 
-The hub runs on `localhost:9999` by default.
+> **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.
 
-### 2. Add to Claude Code
+## Quick Start
 
-**Frontend Terminal:**
+**Machine 1 (Alice):**
 ```bash
-claude mcp add claude-collab -- npx @dolusoft/claude-collab client --team frontend
+claude mcp add claude-collab -- npx -y @dolusoft/claude-collab --name alice
 ```
 
-**Backend Terminal:**
+**Machine 2 (Bob):**
 ```bash
-claude mcp add claude-collab -- npx @dolusoft/claude-collab client --team backend
+claude mcp add claude-collab -- npx -y @dolusoft/claude-collab --name bob
 ```
 
-### 3. Start Collaborating
-
-In your Claude Code session, you can now use these tools:
+Open Claude Code on both machines. Within ~30 seconds they find each other automatically. Then just use the tools:
 
 ```
-# Join a team
-> Ask Claude to join the frontend team
-
-# Ask a question to another team
-> "Ask the backend team: What's the response format for the /users endpoint?"
+# Ask bob a question (alice's terminal)
+ask("bob", "What's the API response format for /users?")
 
-# Check incoming questions
-> "Check my inbox for questions from other teams"
+# Check inbox for incoming questions
+inbox()
 
 # Reply to a question
-> "Reply to question q_123: The endpoint returns JSON with id, name, email fields"
+reply("q_abc123", "It returns JSON: {id, name, email}")
 ```
 
 ## MCP Tools
 
-| Tool | Description | Example |
-|------|-------------|---------|
-| `join` | Join a team channel | `join("frontend")` |
-| `ask` | Ask a question (waits 30s for response) | `ask("backend", "API format?")` |
-| `inbox` | List incoming questions | `inbox()` |
-| `reply` | Reply to a question | `reply("q_123", "Here's the answer...")` |
+| 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
 
 ### Bug Coordination
 
 ```
-Frontend: "Backend team, we're seeing duplicate SignalR messages.
-          Can you check if OnConnectedAsync is being called multiple times?"
+alice: ask("bob", "We're seeing duplicate SignalR messages — can you check if
+       OnConnectedAsync is being called multiple times on your side?")
 
-Backend:  "Found it! Logs show 2 connection IDs for the same user:
-          conn_abc123 - 10:00:01
-          conn_xyz789 - 10:00:01
-          Looks like React StrictMode is causing double connections."
+bob: reply("q_abc", "Found it. Logs show 2 connection IDs for the same user —
+     React StrictMode is causing double connections.")
 ```
 
 ### API Design Sync
 
 ```
-Frontend: "What should the request payload look like for the new checkout flow?"
-
-Backend:  "Here's the schema:
-          ```json
-          {
-            \"items\": [{\"id\": string, \"quantity\": number}],
-            \"paymentMethod\": \"card\" | \"paypal\"
-          }
-          ```"
-```
+alice: ask("bob", "What should the request payload look like for checkout?")
 
-## Configuration
+bob: reply("q_xyz", "Here's the schema:
+     { items: [{id: string, quantity: number}], paymentMethod: 'card' | 'paypal' }")
+```
 
-### Environment Variables
+## Network Requirements
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CLAUDE_COLLAB_PORT` | `9999` | Hub server port |
-| `CLAUDE_COLLAB_HOST` | `localhost` | Hub server host |
+- 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
 
-### CLI Options
+On first run, Windows will ask "Allow this app on the network?" — click **Allow**. This is a one-time prompt per machine.
 
-```bash
-# Hub server
-npx @dolusoft/claude-collab hub start --port 9999 --host localhost
+## Configuration
 
-# Client
-npx @dolusoft/claude-collab client --team frontend --port 9999 --host localhost --auto-hub
-```
+| Env variable | Default | Description |
+|---|---|---|
+| `CLAUDE_COLLAB_PORT_MIN` | `11700` | WS port range start |
+| `CLAUDE_COLLAB_PORT_MAX` | `11750` | WS port range end |
 
 ## Architecture
 
-Claude Collab uses a hub-and-spoke architecture:
-
-```
-                    ┌─────────────────────────────────┐
-                    │           HUB SERVER            │
-                    │     (WebSocket, port 9999)      │
-                    │                                 │
-                    │  ┌─────────┐  ┌─────────────┐   │
-                    │  │ Teams   │  │  Questions  │   │
-                    │  │ Members │  │  Answers    │   │
-                    │  └─────────┘  └─────────────┘   │
-                    └──────────┬──────────────────────┘
-                               │
-              ┌────────────────┼────────────────┐
-              │                │                │
-              ▼                ▼                ▼
-       ┌──────────┐     ┌──────────┐     ┌──────────┐
-       │   MCP    │     │   MCP    │     │   MCP    │
-       │ Client 1 │     │ Client 2 │     │ Client N │
-       │(frontend)│     │(backend) │     │ (devops) │
-       └──────────┘     └──────────┘     └──────────┘
-              │                │                │
-              ▼                ▼                ▼
-       ┌──────────┐     ┌──────────┐     ┌──────────┐
-       │  Claude  │     │  Claude  │     │  Claude  │
-       │   Code   │     │   Code   │     │   Code   │
-       │Terminal 1│     │Terminal 2│     │Terminal N│
-       └──────────┘     └──────────┘     └──────────┘
-```
-
-### Domain-Driven Design
-
-The codebase follows DDD principles with 4 layers:
-
 ```
 src/
-├── domain/          # Entities, Value Objects, Domain Events
-├── application/     # Use Cases, DTOs
-├── infrastructure/  # WebSocket, Repositories
-└── presentation/    # MCP Tools, CLI
+├── 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
+└── presentation/
+    └── mcp/                         # MCP server + tools
 ```
 
 ## Development
 
-### Prerequisites
-
-- Node.js 20+
-- pnpm (recommended) or npm
-
-### Setup
-
 ```bash
 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
 ```
 
-### Commands
-
-```bash
-pnpm build        # Build the project
-pnpm dev          # Watch mode
-pnpm test         # Run tests
-pnpm lint         # Lint code
-pnpm format       # Format code
-```
-
-### Testing
-
-```bash
-pnpm test              # Run all tests
-pnpm test:watch        # Watch mode
-pnpm test:coverage     # With coverage
-```
-
-## Contributing
-
-Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) first.
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details.
-
-## Acknowledgments
-
-- Built with [Model Context Protocol (MCP)](https://modelcontextprotocol.io)
-- Inspired by the need for better AI-assisted team collaboration
-- Created by [Dolusoft](https://github.com/dolusoft)
+MIT — see [LICENSE](LICENSE) for details.
 
 ---
 
-**Note:** This project is in active development. Features may change.
+Created by [Dolusoft](https://github.com/dolusoft) · Built with [Model Context Protocol](https://modelcontextprotocol.io)