# Claude Bridge

Real-time collaboration bridge between two Claude Code instances. Two developers, each with their own Claude, can work together with shared chat channels and Claude-to-Claude communication.

## Quick Start

```bash
# Terminal 1: Start the relay server (one person hosts this)
node src/relay/index.js

# Terminal 2: Start the bridge
node bin/claude-bridge.js
```

Browser opens at `http://localhost:3847`. Enter your name, click **Create Session**, and share the 6-digit code with your collaborator.

Your collaborator runs:
```bash
CLAUDE_BRIDGE_RELAY=ws://<YOUR_IP>:3848 node bin/claude-bridge.js
```
They enter the code and you're connected.

## Features

- **Human Chat** — Direct messaging between collaborators
- **Claude Team** — Shared channel where both humans can post instructions that both Claude instances see
- **MCP Integration** — Claude Code gets `bridge_read_messages`, `bridge_send_message`, and `bridge_status` tools
- **Real-time** — WebSocket-based, instant message delivery
- **Cross-network** — Works through NAT via relay server
- **Zero config** — Single command to start, 6-digit code to connect

## Architecture

```
[Your Machine]                    [Relay Server]                [Their Machine]
Claude Code CLI                                                 Claude Code CLI
  ↕ MCP (stdio)                                                   ↕ MCP (stdio)
Bridge Agent ←——— WebSocket ———→ Relay Server ←——— WebSocket ———→ Bridge Agent
  ↕ HTTP/WS                                                       ↕ HTTP/WS
Web UI (browser)                                                Web UI (browser)
```

## Channels

| Channel | Who sees it | Purpose |
|---------|------------|---------|
| Human Chat | Both humans | Direct messaging |
| Claude Team | Both humans + both Claudes (via MCP) | Shared instructions, task coordination |

## MCP Tools (available to Claude Code)

| Tool | Description |
|------|-------------|
| `bridge_read_messages` | Read messages from a channel (`human` or `claude-team`) |
| `bridge_send_message` | Send a message to a channel |
| `bridge_status` | Get session status (connected, peer name, etc.) |

## Deploying the Relay

The relay server is stateless and lightweight. Deploy anywhere:

```bash
# Docker
docker build -f Dockerfile.relay -t claude-bridge-relay .
docker run -p 3848:3848 claude-bridge-relay

# Or directly
PORT=3848 node src/relay/index.js
```

Then set `CLAUDE_BRIDGE_RELAY=ws://your-server:3848` when starting the bridge.

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `CLAUDE_BRIDGE_RELAY` | `ws://localhost:3848` | Relay server URL |
| `PORT` | `3848` (relay) | Relay server port |

## Ports

| Port | Service |
|------|---------|
| 3847 | Bridge web UI |
| 3848 | Relay server |
| 3849 | MCP IPC (local only) |
