npm package: @habibsoula/claude-collab
Description: Collaborate with teammates through Claude Code
Latest version: 1.0.10

# Claude Collab

Real-time collaboration for Claude Code users. Route questions to the right teammate's Claude Code session based on domain expertise.

## Why?

When developers work on the same project with Claude Code separately:
- Developer A (Frontend) asks about the backend → their Claude lacks context
- Manual copy-paste between sessions breaks flow
- Both context windows get polluted with cross-domain info

**Claude Collab fixes this.** Questions automatically route to the expert's session, using their tokens and context.

## How It Works

```
┌─────────────────┐         ┌─────────────────┐
│  Mohamed        │         │  Ahmed          │
│  (Frontend)     │         │  (Backend)      │
│                 │         │                 │
│  Claude Code    │◄───────►│  Claude Code    │
└────────┬────────┘   WS    └────────┬────────┘
         │                           │
         └───────────┬───────────────┘
                     │
              ┌──────▼──────┐
              │ Team Server │
              │ (WebSocket) │
              └─────────────┘
```

## Quick Start

### 1. Install CLI

```bash
npm install -g @habibsoula/claude-collab
```

### 2. Create a Team

```bash
claude-collab init
```

This will:
- Guide you through server deployment (Deno Deploy recommended)
- Generate an invite code
- Configure MCP integration

### 3. Invite Teammates

Share the invite code:

```bash
claude-collab join WXKM4NPR
```

### 4. Collaborate

In Claude Code, questions are automatically routed:

> "How does the auth endpoint validate tokens?"

Claude Code recognizes this as a backend question and routes it to Ahmed's session.

## Commands

| Command | Description |
|---------|-------------|
| `claude-collab init` | Create a new team |
| `claude-collab join <code>` | Join existing team |
| `claude-collab status` | Show team & online members |
| `claude-collab invite` | Generate new invite code |
| `claude-collab config` | View/edit configuration |
| `claude-collab leave` | Leave the team |

## MCP Tools

Once configured, Claude Code gains these tools:

- **ask_teammate** - Ask a question to a specific role (e.g., "backend")
- **ask_service** - Ask whoever owns a service (e.g., "payment-service")
- **broadcast** - Ask all online team members
- **team_status** - See who's online

## Self-Hosting the Server

### Option 1: Deno Deploy Playground (Easiest - No GitHub Required)

1. Go to [dash.deno.com/playground](https://dash.deno.com/playground)
2. Replace the code with:
```typescript
const TEAM_NAME = "your-team-name"; // Change this!

const { default: server } = await import(
  "https://raw.githubusercontent.com/HabibPro1999/claude-collab/main/server/deno/server.ts"
);
```
3. Click **Deploy**
4. Copy your URL (e.g., `https://your-project.deno.dev`)

### Option 2: Run from URL (Any Machine with Deno)

```bash
TEAM_NAME="my-team" deno run --allow-net --allow-env \
  https://raw.githubusercontent.com/HabibPro1999/claude-collab/main/server/deno/server.ts
```

### Option 3: Deno Deploy with GitHub

```bash
cd server/deno
deployctl deploy --project=my-team server.ts
```

### Option 4: Local Development

```bash
cd server/deno
TEAM_NAME="my-team" deno run --allow-net --allow-env server.ts
```

Expose locally with ngrok: `ngrok http 8080`

## Configuration

Config is stored in `.claude/collab.yaml`:

```yaml
version: 1
team:
  id: "abc123"
  name: "my-startup"
  server: "wss://my-team.deno.dev"
  inviteCode: "WXKM4NPR"
me:
  name: "mohamed"
  role: "frontend"
  keywords:
    - react
    - css
    - ui
```

## Architecture

- **Firebase Realtime Database** - Global invite code registry (free tier)
- **Team Server** - WebSocket broker you host (Deno Deploy free tier)
- **CLI** - npm package for setup and MCP bridge
- **MCP Integration** - Exposes collaboration tools to Claude Code

## Security

- All WebSocket connections use TLS (WSS)
- Questions/answers pass through your server only (never stored)
- Invite codes expire after 7 days
- Each team hosts their own isolated server

## Requirements

- Node.js 18+
- Claude Code with MCP support
- Deno (for server, or use Docker)

## License

MIT