AgentBrain Handoffs

Exact, durable handoffs between AI coding agents. Each handoff is one new turn in the recipient's existing session.

_{Real screenshot of the demo; the data in it is invented sample data.}

pip install .
handoffs demo

Open the URL it prints (http://127.0.0.1:8765/). Four simulated agents hand work to each other. Ctrl+C stops and deletes the demo data.

Why this exists

A team of coding agents already has sessions, inboxes and tools. What it lacks is delivery: a message that reaches the right session, waits if that agent is busy, is sent once, and is retried within a bound when the provider drops it.

Without that, handoffs get lost, delivered twice, or pasted into a session that is already in the middle of a turn. AgentBrain Handoffs is the delivery layer. It is a local Python package (Python 3.9+, standard library only) with a command handoffs, a live page, and an MCP server.

60-second quickstart

From a clone of this repository:

python3 -m venv .venv
.venv/bin/pip install .
.venv/bin/handoffs demo

Or, once the package is on PyPI:

pipx run agentbrain-handoffs demo

You should see:

AgentBrain Handoffs demo
  Open http://127.0.0.1:8765/
  Four simulated agents (Planner, Engineer, Reviewer, Writer) hand work to each other.
  Nothing real is contacted. The demo data is temporary and deleted when you stop (Ctrl+C).

The page updates every few seconds. Handoffs move through Accepted → Working → Finished. Work is returned and closed on its own. --speed 4 makes the simulated turns finish faster.

To keep the demo on another port: handoffs demo --port 9876.

A longer walkthrough, including your own agents, is in docs/QUICKSTART.md.

Concepts

A handoff is a message addressed to one registered agent. The delivery engine turns it into exactly one new turn for that agent, at the session it had when the handoff was enrolled.

A work contract is a handoff with a title. The recipient returns a result (or a blocker); the sender closes it as accepted, revision, or blocked. A due time is optional; if it passes, the sender gets one non-waking reminder.

Delivery states, in plain words:

Guarantees

1. Exact recipient. A handoff is delivered only to the agent it was addressed to, at the endpoint it had when enrolled.
2. One write per attempt. The attempt is reserved before sending. A lost reply goes to UNCERTAIN and is reconciled by observation. A refused write is retried once; a second refusal ends the delivery as FAILED, so it never holds the recipient.
3. Never interrupt. A busy recipient keeps its turn. A second handoff to the same agent waits as BUSY.
4. Bounded resend. An errored turn is resent up to twice; an interrupted turn once, after ten minutes, and only while the work is still open. Each resend has a new request id.
5. Honest release. An UNCERTAIN delivery that three complete history scans over an hour prove was never received is CANCELLED. An accepted turn nobody can observe for 10 minutes becomes UNCERTAIN, so the same rule applies. When you know how a stuck delivery ended, handoffs release ID cancels it; nothing is resent either way.
6. Outages hold. A provider status-page guard can hold delivery without spending an attempt.
7. Deadlines. Work past its due time alerts the sender once, as a non-waking notification.

Adapters

See docs/ADAPTERS.md for settings, examples and the experimental caveats.

MCP

Each agent session launches its own MCP server. The identity is fixed at start, so a tool call cannot act as another agent.

Claude Code

claude mcp add handoffs -- handoffs mcp --agent me

Replace me with the agent id you registered (handoffs agent add me --provider claude-code ...).

Codex (~/.codex/config.toml)

[mcp_servers.handoffs]
command = "handoffs"
args = ["mcp", "--agent", "me"]

Cursor (MCP servers in Cursor settings)

{
  "mcpServers": {
    "handoffs": {
      "command": "handoffs",
      "args": ["mcp", "--agent", "me"]
    }
  }
}

Point every process at the same database with --db or HANDOFFS_DB. The engine (handoffs serve or handoffs run) is what actually delivers; the MCP server only writes to the inbox. Details: docs/MCP.md.

Project memory: the ContextLib plugin

ContextLib keeps a project's decisions, facts and lessons as plain Markdown files. Install it and point the same server at a library, and each agent gets the context_* tools (brief, search, get, record, supersede, review, capture, export, import, status) next to its handoff tools:

pip install "git+https://github.com/willykeenan/agentbrain-contextlib"
claude mcp add handoffs -- handoffs mcp --agent me --context-library "/Volumes/SSD/ContextLib"

$CONTEXTLIB_ROOT works in place of the flag. The plugin runs as the server's fixed agent id, so an agent's records are authored by exactly the agent that sent its handoffs. Without a library, the server offers handoff tools only.

CLI

handoffs init
handoffs agent add planner --provider demo
handoffs agent add builder --provider demo --name Builder
handoffs send planner builder "Add a health check" --title "Health check" --due-minutes 30
handoffs serve                          # engine + live page on http://127.0.0.1:8765/
handoffs inbox builder
handoffs read ID --as builder
handoffs return ID --as builder --summary "Health check is green"
handoffs close ID --as planner accepted
handoffs status --json
handoffs tick                           # one delivery pass (Codex and Claude Code turns wait for run or serve)
handoffs release ID                     # stop tracking a stuck delivery; never resent
handoffs run                            # engine only
handoffs mcp --agent builder            # stdio MCP server

--db PATH or HANDOFFS_DB selects the database (default ./.handoffs/handoffs.sqlite3). --json is accepted on the commands that print records. Usage errors exit 2.

Security

The live page binds to loopback and refuses non-loopback Host headers (DNS-rebinding). POST /api/send needs the token in <db>.token (mode 0600). --public-demo exists only on handoffs demo (simulated agents, temporary data); that page cannot send and shows plain state sentences instead of adapter errors. MCP identity is the --agent you started with. Full model: docs/SECURITY-MODEL.md.

Roadmap

• Keep the demo and command adapters stable.
• Harden the Codex and Claude Code adapters as those app protocols settle.
• More status-page presets for outageGuard.
• Planned: Agent Rooms will use this delivery contract.

Run with Docker

The image is published at ghcr.io/willykeenan/agentbrain-handoffs for Apple silicon and Intel.

docker run --rm -p 8765:8765 ghcr.io/willykeenan/agentbrain-handoffs demo --host 0.0.0.0 --public-demo   # the live demo
claude mcp add handoffs -- docker run -i --rm -v ~/.handoffs:/data ghcr.io/willykeenan/agentbrain-handoffs mcp --agent me

The MCP server writes to the handoff database in ~/.handoffs; run the engine (handoffs serve) on the machine where your agents live so it can deliver.

License

Apache-2.0. Copyright KE Studios.