AgentBrain Handoffs MCP server

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

Shortened. The full README is on GitHub.