AgentBrain Handoffs

Name: AgentBrain Handoffs
Author: willykeenan

by willykeenanversion 0.1.0i★ –iRuns on your computer

Registry nameio.github.willykeenan/agentbrain-handoffs

Install

Overview

Description from the maker (original English)

Exact, durable handoffs between AI coding agents: one turn in the right session, never twice.

PopNx MCP’s three pillars

These three are never merged into one score: opinions, measurements and popularity are different things.

User voiceiNo reviews yetReviews open together with accounts in a later step
Our basic checksi1 of 1 passedChecked from public information; code not scanned yet
UsageiNot measured yet★ –

What you can do with it

We have not written a plain-language summary for this one yet. Below are the facts we read from the registry.

Connection: Runs on your computer
Transport: stdio
Category: Developer tools

Install

Pick the AI app you use, then copy the settings.

Before you install

Basic checks: 1 of 1 passed
Runs on your computer with your user’s permissions (files, network, apps).
The registry lists no key to fill in.

You need

DockerDocker installed

Which app do you use?

ClaudeClaude CodeCursorVS CodeChatGPT

Pick your app above. We remember it, so next time the button says “Install in …”.

Open Claude Desktop → Settings → Developer → Edit Config, and paste this into claude_desktop_config.json

{
  "mcpServers": {
    "agentbrain-handoffs": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/willykeenan/agentbrain-handoffs:0.1.0",
        "mcp",
        "--agent",
        "{agent_id}"
      ]
    }
  }
}

Run this in your terminal

claude mcp add agentbrain-handoffs -- docker run -i --rm ghcr.io/willykeenan/agentbrain-handoffs:0.1.0 mcp --agent '{agent_id}'

Open in Cursor

Or copy the settings yourself

Paste into .cursor/mcp.json in your project, or ~/.cursor/mcp.json

{
  "mcpServers": {
    "agentbrain-handoffs": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/willykeenan/agentbrain-handoffs:0.1.0",
        "mcp",
        "--agent",
        "{agent_id}"
      ]
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

Open in VS Code

Or copy the settings yourself

Paste into .vscode/mcp.json in your project

{
  "servers": {
    "agentbrain-handoffs": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/willykeenan/agentbrain-handoffs:0.1.0",
        "mcp",
        "--agent",
        "{agent_id}"
      ]
    }
  }
}

Your browser asks to open the app, then the app shows the settings and asks you to confirm. Key values are left empty for you to fill in.

This one runs on your computer, and ChatGPT can only connect to servers on the internet. Pick another app.

Your choice stays on this device in a cookie; no account needed.

These settings are generated from the maker’s registry entry. If the README says otherwise, follow the README.

What it can do

Runs on your computer; the tool list appears in your AI app after you install it.

Basic checksi

We check information anyone can see; we have not read the code. Checks that do not apply are left out of the count. · Checked Nov 8, 2026

✓ Pass
Maker matches the repo
The registry name was verified with the GitHub account willykeenan, which owns the repo
… Not checked yet
Still maintained
We have not read this repo from GitHub yet
… Not checked yet
Has a licence
We have not read this repo from GitHub yet
– Not applicable
Endpoint responds
This one runs on your computer; there is no internet endpoint
– Not applicable
Sign-in with OAuth
Runs on your computer and uses local settings instead
… Not checked yet
No hidden instructions in tool descriptions
Runs on your computer; we can only read tool lists from internet endpoints

Compared with others in Developer toolsi

More stars than 0% of the other 4919 servers in this category
Published to the registry more recently than 52% of the other 4919 servers in this category
Basic checks equal to or better than 100% of the other 4919 servers in this category

Compared with every active server in this category in the registry. Stars count only when the publisher owns the repo.

Common questions

Is AgentBrain Handoffs safe?

It passed 1 of 1 applicable basic checks. We have not read the code. Before adding a key or token, see what access the server asks for and use a key with only the permissions you need.

What keys or codes does it need?

The registry does not list a required key, though some servers ask you to sign in on first use.

Does it run on my computer or in the cloud?

It runs on your computer. Your AI app starts it when needed, and data does not pass through the maker’s servers (unless it calls an online service itself).

Is it still maintained?

The GitHub repo last changed –, and the latest version (0.1.0) reached the registry 42 days ago.

Which apps can use it?

Apps that support MCP, such as Claude Desktop, Claude Code, Cursor and VS Code. You also need Docker on your computer.

What can I use instead?

In the same category: GitHub, Desktop Commander, Cloudflare MCP

Alternatives

Servers in the same category from other makers, sorted by stars.

Reading a card:★ GitHub starsiThree pillars: reviews · checks · usageiUpdated = latest version published to the registryi

GitHub

by github

GitHub’s official server lets AI read and manage code, issues and pull requests in your account. Use GitHub’s hosted version or run it locally with Docker.

Computer or cloud★ 34,245MITUpdated 4 days ago

Install

Desktop Commander

by wonderwhy-er

MCP server for terminal commands, file operations, and process management

Runs on your computer★ 10,225MITUpdated 17 days ago

Install

Cloudflare MCP

by cloudflare

Cloudflare MCP servers

Runs in the cloud★ 4,446Apache-2.0Updated 14 months ago

Install

README from the maker

Open the README

Copied from the maker’s repo as written. PopNx MCP has not reviewed or endorsed it. HTML, images and scripts are removed. Links lead off this site.

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:

State	Meaning
WAITING	Queued. Next engine pass will try to send it. A provider outage stays here too: the detail explains the hold and no attempt is used.
BUSY	The recipient is in the middle of a turn. This waits.
HELD	Blocked on purpose: the connection is blocked or delivery is paused. No attempt used.
UNAVAILABLE	The agent or its session is gone. Nothing is redirected.
OWNER_REJECTED	The session refused the write. One retry is allowed.
SENDING	The write is in flight.
UNCERTAIN	The write may have landed; the reply was lost, or an accepted turn could not be observed for 10 minutes. Observed, never resent.
ACCEPTED	The recipient's session took the turn.
RUNNING	The turn is in progress.
RETURNED	The turn finished.
FAILED	The turn failed or was interrupted, or the session refused it twice (then it was never delivered).
ACKNOWLEDGED	The recipient read the message; no separate turn is needed.
CANCELLED	Proven absent after enough history scans, or released by a person with `handoffs release`. Not resent.
DUPLICATE	Identical to a handoff still in progress.

Guarantees

Exact recipient. A handoff is delivered only to the agent it was addressed to, at the endpoint it had when enrolled.
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.
Never interrupt. A busy recipient keeps its turn. A second handoff to the same agent waits as BUSY.
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.
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.
Outages hold. A provider status-page guard can hold delivery without spending an attempt.
Deadlines. Work past its due time alerts the sender once, as a non-waking notification.

Adapters

Provider	Status	What it talks to
`demo`	Stable	Simulated agents. Used by `handoffs demo`.
`command`	Stable	An argv (no shell) or an HTTP POST.
`codex`	Experimental	`codex app-server` JSON-RPC over stdio.
`claude-code`	Experimental	Claude Code headless (`claude -p --resume`).

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.

Command	Purpose
`init`	Create the database.
`agent add\	list\	remove`	Register agents. `--set KEY=VALUE` is JSON when it parses.
`allow` / `block`	Directed connections.
`config KEY VALUE`	`enabled`, `enabledAfter`, `connections`, `outageGuard`.
`send FROM TO MESSAGE`	Inbox message; `--title` makes it work. `--key` is idempotent.
`inbox` / `read` / `accept` / `return` / `close`	Work lifecycle. `--as` or `HANDOFFS_AGENT`.
`status` / `tick` / `run` / `serve` / `mcp` / `demo`	Inspect and deliver.
`release ID`	Cancel one stuck delivery (for example UNCERTAIN) so its recipient is free. Nothing is sent.

Security

The live page binds to loopback and refuses non-loopback Host headers (DNS-rebinding). POST /api/send needs the token in .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.

Source: github.com/willykeenan/agentbrain-handoffs. Live demo: huggingface.co/spaces/willykeenan/agentbrain-handoffs.

AgentBrain Handoffs is the open delivery layer for AgentBrain, the agent runtime coming to Agent Rooms (agentrooms.io).

AgentBrain Handoffs

Overview

PopNx MCP’s three pillars

What you can do with it

Install

Before you install

What it can do

Basic checksi

Maker matches the repo

Still maintained

Has a licence

Endpoint responds

Sign-in with OAuth

No hidden instructions in tool descriptions

Compared with others in Developer toolsi

Common questions

Alternatives

GitHub

Desktop Commander

Cloudflare MCP

README from the maker

AgentBrain Handoffs

Why this exists

60-second quickstart

Concepts

Guarantees

Adapters

MCP

Project memory: the ContextLib plugin

CLI

Security

Roadmap

Run with Docker

License