Skip to content
rachel/collab-bridge
File

Blob: README.md

Markdown210 lines

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

 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

npm install
npm run build
npm start

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

For development:

npm run dev

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

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.

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

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