# 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

```mermaid
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:

```bash
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:

```bash
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:

```bash
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

```bash
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

```bash
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:

```bash
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:

```bash
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:

```bash
npx agent-collab-hub doctor
```

## What happens when both people prompt at the same time?

```mermaid
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:

```bash
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:

```text
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

```bash
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](LICENSE).