Agent Collab MCP

Agent Collab MCP connects coding agents owned by different people to one shared coordination hub. Codex can work on the backend while Claude Code works on the frontend, both at the same time, without sharing a checkout or silently overwriting each other's work.

It combines Git isolation with active coordination:

• a unique branch and worktree for every agent
• an atomic shared task queue
• capability-aware task recommendations
• exclusive leases for files, components, APIs, and database surfaces
• typed messages, acknowledgements, plans, progress, and handoffs
• persistent identities and inboxes across new AI conversations
• prompt-start and response-end inbox gates for Codex and Claude Code
• a durable SQLite audit trail

The public install package is named agent-collab-hub.

How everything connects

flowchart LR
  subgraph A["Alice's computer"]
    AC["Codex"]
    AW["Backend worktree<br/>agent/alice/backend"]
    AH["Prompt hooks"]
    AP["Local MCP relay"]
    AC --> AW
    AH --> AC
    AC <--> AP
  end

  subgraph H["Shared host"]
    API["Agent Collab MCP<br/>HTTPS /mcp"]
    DB[("SQLite<br/>tasks · inboxes · leases · plans")]
    API <--> DB
  end

  subgraph B["Bob's computer"]
    CC["Claude Code"]
    BW["Frontend worktree<br/>agent/bob/frontend"]
    CH["Prompt hooks"]
    CP["Local MCP relay"]
    CC --> BW
    CH --> CC
    CC <--> CP
  end

  AP <--> API
  CP <--> API
  AW --> G["Git pull requests + CI"]
  BW --> G

Both machines need network access to the same hub. That hub can run on one teammate's always-on computer over a private network, a small cloud server behind HTTPS, or Docker hosting. There is no way for two disconnected computers to exchange live coordination state without some shared transport.

Install without cloning this repository

Requirements:

• Node.js 22.13 or newer
• Git
• Codex, Claude Code, or another MCP-capable client
• separate branches/worktrees for each agent

Until the npm package is published, replace npx agent-collab-hub below with:

npx --yes --package github:Nathan-Z01/agent-collab-mcp agent-collab-hub

1. Run one shared hub

On the computer or server that will stay reachable:

npx agent-collab-hub serve --public --data ./agent-collab.sqlite

If you do not pass --token, the command creates a strong token, prints it once, and saves it beside the SQLite file with private file permissions so restarts keep the same identity boundary. Save it in a password manager and share it privately with your teammate. --public listens on all interfaces; put the service behind a private network such as Tailscale or an HTTPS reverse proxy before using it across the internet.

You can provide explicit settings instead:

npx agent-collab-hub serve \
  --host 0.0.0.0 \
  --port 8787 \
  --data ./agent-collab.sqlite \
  --token "a-long-random-secret-at-least-24-characters" \
  --allowed-hosts "collab.example.com,localhost"

2. Create the shared project once

npx agent-collab-hub create-project \
  --url https://collab.example.com/mcp \
  --token "YOUR_SHARED_TOKEN" \
  --name "Our app" \
  --repository https://github.com/your-team/your-app

Share the returned projectId, hub URL, and token privately with your teammate.

3. Give each agent its own worktree

git worktree add ../your-app-backend -b agent/alice/backend main
git worktree add ../your-app-frontend -b agent/bob/frontend main

Never point both agents at the same directory.

4. Install Agent Collab in each worktree

Alice runs this inside her backend worktree:

npx agent-collab-hub install \
  --url https://collab.example.com/mcp \
  --token "YOUR_SHARED_TOKEN" \
  --project "PROJECT_ID" \
  --name backend-agent \
  --owner "Alice" \
  --client Codex \
  --branch agent/alice/backend \
  --capabilities backend,api,database,testing

Bob runs the same installer inside his frontend worktree with his own identity:

npx agent-collab-hub install \
  --url https://collab.example.com/mcp \
  --token "YOUR_SHARED_TOKEN" \
  --project "PROJECT_ID" \
  --name frontend-agent \
  --owner "Bob" \
  --client "Claude Code" \
  --branch agent/bob/frontend \
  --capabilities frontend,ui,accessibility,testing

The installer safely merges, rather than replaces, existing configuration. It adds:

File	Purpose	Committed?
.codex/config.toml	Connects Codex to the local secure MCP relay	Yes
.codex/hooks.json	Checks the inbox at prompt start and response end	Yes
.claude/settings.json	Adds the same lifecycle gates to Claude Code	Yes
.mcp.json	Connects Claude Code to the local secure MCP relay	Yes
AGENTS.md / CLAUDE.md	Teaches both agents the coordination protocol	Yes
.agent-collab/credentials.json	Token and persistent identity for one worktree	No—ignored
.agent-collab/bin/*	Dependency-free hook and relay adapters	No—ignored

When --client Codex is selected, the installer also registers the private relay as agent-collab in that user's Codex configuration. Re-running the installer from another worktree intentionally repoints that one managed Codex entry. Claude Code reads the project-level .mcp.json directly.

Restart the AI client from that worktree and approve the project hooks/MCP server when asked. Verify everything with:

npx agent-collab-hub doctor

What happens when both people prompt at the same time?

sequenceDiagram
  participant C as Codex backend
  participant H as Shared hub
  participant L as Claude frontend

  par Both prompts begin
    C->>H: begin_turn + read inbox/state
    L->>H: begin_turn + read inbox/state
  end
  C->>H: claim backend task
  L->>H: claim frontend task
  C->>H: reserve api:checkout + path:server/**
  L->>H: reserve component:checkout-ui + path:web/**
  H-->>C: leases granted
  H-->>L: leases granted
  L->>H: contract: UI needs POST /api/checkout
  H-->>C: message waiting
  C->>H: fetch inbox at milestone
  C->>H: acknowledge contract + implement endpoint
  C->>H: report tests and commit
  L->>H: report tests and commit
  par Both responses finish
    C->>H: finish_turn
    L->>H: finish_turn
  end

Atomic claims and reservations decide collisions at the server. If both agents request the same exclusive resource, one lease succeeds and the other is rejected with a conflict message; no agent is allowed to erase the other's branch.

The agents do not telepathically infer every cross-layer change. The frontend agent publishes a plan and sends a contract message describing the endpoint or data shape it needs. The backend agent sees it at its next inbox check, acknowledges it, and implements against that contract. Agents check at the start of every prompt, after meaningful milestones, and immediately before responding. A hook cannot interrupt a model in the middle of one tool call, but the end gate blocks a normal response when a new critical message is still waiting.

Docker deployment

After a public release, run the prebuilt image:

docker run -d \
  --name agent-collab-hub \
  --restart unless-stopped \
  -p 8787:8787 \
  -e COLLAB_MCP_TOKEN="a-long-random-secret-at-least-24-characters" \
  -v agent-collab-data:/data \
  ghcr.io/nathan-z01/agent-collab-mcp:latest

Or clone the repository and use COLLAB_MCP_TOKEN=... docker compose up -d.

Do not expose plain HTTP directly to the public internet. Use TLS or a private network. Back up the /data volume.

MCP tools

Tool	Purpose
create_project	Create the shared coordination space
register_agent / resume_agent / disconnect_agent	Manage persistent identities and temporary sessions
begin_turn / finish_turn	Enforce inbox checks at prompt and response boundaries
heartbeat	Keep a session active
create_task / recommend_agents / claim_task	Match work to strengths and atomically assign it
publish_plan	Announce the approach, resources, and interface contracts
reserve_resources / release_resources	Lease physical and logical edit surfaces
send_message / fetch_inbox / acknowledge_message	Durable agent-to-agent communication
report_progress	Publish commits, tests, blockers, and actual changed resources
resolve_conflict	Record an agreed resolution
complete_task	Finish work and release task leases
get_project_state	Inspect agents, tasks, plans, leases, and conflicts

Resources are project-relative and typed:

path:src/auth/**
path:backend/routes/session.ts
component:authentication
api:session-v2
db:users-schema

An exclusive reservation on path:src/auth/** conflicts with path:src/auth/login.ts. Different types do not conflict automatically, so plans should declare both physical paths and logical interfaces.

Security model

The MVP has three authentication layers:

• one bearer token protects access to the shared hub
• a persistent identity key reconnects an agent across conversations
• a replaceable per-session key authenticates the current agent session

Identity and session keys are hashed in the database. Tokens and returned keys stay in the ignored .agent-collab/credentials.json file. Remote mode refuses to start without a server token of at least 24 characters.

For a small trusted team, a shared hub token is practical. A larger or untrusted team should add per-human OAuth/OIDC, project roles, rate limiting, and managed backups before production use.

What it prevents—and what it cannot

It prevents silent live-file overwrites by enforcing different branches and rejecting duplicate active branch registration. It prevents participating agents from intentionally entering an already leased surface. It preserves messages, plans, and conflicts for both people to inspect.

It cannot prove that changes in different files are semantically compatible, stop an agent that ignores all repository instructions, or replace code review. Keep protected branches, pull requests, tests, and preferably a merge queue. Git remains the source of truth; Agent Collab coordinates the work around it.

Development

npm install
npm run check
npm test
npm run build
npm pack --dry-run

The test suite covers branch uniqueness, persistent reconnects, inbox transfer, prompt-boundary gates, capability matching, atomic claims, all-or-nothing reservations, lease expiry, acknowledgements, changed-resource conflicts, migrations, installer merging, and the standalone MCP relay.

Licensed under the MIT License.