# collab-bridge

`collab-bridge` is a small MCP-based bridge for running a live collaboration between exactly two agents: Claude and Codex.

It does not try to be a general orchestration platform. It gives you:

- two MCP endpoints
- one shared session
- one simple message protocol
- optional human review before delivery
- a lightweight web UI for prompts, monitoring, and phase control

That narrow scope is deliberate. The point is to keep the collaboration loop understandable, inspectable, and easy to operate.

## What This Is

Use `collab-bridge` when you want to:

- make Claude and Codex work a shared task together
- keep a human operator in the loop
- intercept, edit, or reject messages before they cross the bridge
- run a simple structured workflow without adopting a larger agent platform

## What This Is Not

`collab-bridge` is intentionally not:

- a general multi-agent runtime
- an agent discovery or routing system
- a durable workflow engine
- a hosted SaaS product
- a universal protocol layer for arbitrary agent ecosystems

State is in-memory. Restarting the server clears sessions.

## How It Works

```text
 Claude <──MCP──> collab-bridge <──MCP──> Codex
                      |
                   Web UI
         (prompts / monitor / moderate / phase control)
```

1. The server exposes two MCP endpoints, one for each agent.
2. A session defines a goal, a workflow template, and which agent starts first when the workflow allows that to vary.
3. The server generates tailored system prompts for both agents with tool instructions and collaboration rules.
4. The operator pastes those prompts into Claude and Codex.
5. The agents exchange messages through the bridge.
6. With auto-forward off, each message waits for human review before delivery.

## Current Model

The bridge keeps the collaboration model intentionally small:

- `collab_send_message` is non-blocking and writes one message into the session
- `collab_wait_for_reply` long-polls for the next delivered message
- only the latest message is returned to save agent context
- skipped older messages are reported with warnings so agents can ask for a superseding full-state message
- `collab_close_session` closes the loop and unblocks waiters
- workflow phases are optional, but when enabled the wait response also includes a `phaseHint`

## Quick Start

```bash
npm install
npm run build
npm start
```

The default URL is `http://localhost:4100`.

For development:

```bash
npm run dev
```

Set a custom port with `--port` or the `PORT` environment variable:

```bash
npm start -- --port 5000
PORT=5000 npm run dev
```

## Usage

1. Open `http://localhost:4100` in a browser.
2. Click `+ New Session`.
3. Choose a workflow, enter the goal, and pick the initiator if that workflow does not force one.
4. Open the `Prompts` tab and paste each generated prompt into the corresponding agent.
5. Watch the conversation in the `Chat` tab.
6. If the workflow has phases, advance or rewind the current phase from the UI.
7. Close a finished session or use `Save Transcript` to export the exchange as a `.txt` file.

### Auto-Forward vs Review Mode

- Auto-forward on: messages are delivered immediately.
- Auto-forward off: messages land as `pending` until the operator delivers, edits, or rejects them.

## Workflow Templates

The server supports pluggable workflow templates in [`src/workflows.ts`](src/workflows.ts).

Current built-in templates:

- `custom`: freeform collaboration with the generic prompt contract only
- `research`: read-only collaboration where Claude owns synthesis and Codex investigates complementary areas
- `implementation`: Claude plans with Codex, waits for user confirmation, implements, then loops with Codex review
- `implementation_codex_architect`: Codex leads architecture, Claude writes the implementation plan, the user gates coding, then Claude implements and Codex reviews

Workflows can define:

- a forced initiator
- named phases
- role-specific contracts
- start instructions
- subagent hints
- receiver-facing phase reminders returned by `collab_wait_for_reply`

## Architecture

```text
src/
  index.ts         Express app: REST API, MCP routes, SSE, static serving
  store.ts         In-memory session/message store, EventEmitter pub/sub
  mcp-handler.ts   Per-request MCP server with collab tools
  prompts.ts       Prompt generation from workflow + role
  workflows.ts     Workflow templates, phases, role contracts
web/
  index.html       Single-file UI (vanilla JS + SSE)
```

Key design choices:

- MCP handlers are stateless per request. Persistent data lives in `Store`.
- Message waiting uses long-poll plus `EventEmitter`, with a race-window re-check after listener registration.
- `collab_wait_for_reply` returns only the most recent delivered message.
- Human moderation is a toggle on each session, not a separate deployment mode.

## API

### Workflows

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/workflows` | List workflow summaries for the UI |

### Sessions

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/sessions` | List sessions |
| `POST` | `/api/sessions` | Create session with `{ goal, workflow?, initiator? }` |
| `GET` | `/api/sessions/:id` | Get session |
| `PATCH` | `/api/sessions/:id` | Update `{ autoForward?, goal?, currentPhaseIndex? }` |
| `POST` | `/api/sessions/:id/close` | Close a session with optional `{ reason }` |
| `DELETE` | `/api/sessions/:id` | Delete session |

Notes:

- `workflow` defaults to `custom`
- some workflows force the initiator, so `initiator` may be ignored or hidden by the UI
- `currentPhaseIndex` is only valid for workflows that define phases

### Messages

| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/sessions/:id/messages/:mid/deliver` | Deliver a pending message |
| `PATCH` | `/api/sessions/:id/messages/:mid` | Edit a pending message with `{ body }` |
| `DELETE` | `/api/sessions/:id/messages/:mid` | Reject a pending message |

### Prompts

| Method | Path | Description |
|--------|------|-------------|
| `GET` | `/api/sessions/:id/prompts` | Generate prompts for both agents |

### MCP Endpoints

| Endpoint | Agent |
|----------|-------|
| `POST /mcp/claude` | Claude |
| `POST /mcp/codex` | Codex |

### SSE

`GET /events` streams UI update events in real time.

## MCP Tools

Both MCP endpoints expose the same tools, scoped to the calling agent:

- `collab_send_message` `{ collabId, message }`: send a message to the other agent
- `collab_wait_for_reply` `{ collabId, lastSeenMessageId }`: long-poll for the next delivered message, returning only the latest one
- `collab_close_session` `{ collabId, reason? }`: close the session once collaboration is explicitly complete

When the active workflow has phases, `collab_wait_for_reply` also includes a `phaseHint` object so the receiving agent can align its next turn with the current phase. If multiple delivered messages are skipped by the latest-only wait model, the response includes `skippedMessageIds` and a warning.

## Why Keep It Small

Most multi-agent projects grow by adding abstractions: discovery, persistence, general routing, agent graphs, provider layers, tracing, auth, and hosted infrastructure.

This project takes the opposite position: for a two-agent collaboration bridge, those layers are usually not necessary yet. A smaller system is easier to inspect, easier to debug, and easier for a human operator to trust.

## License

MIT