Skip to content
MCP server

AgentBrain Handoffs

Exactly-once delivery of handoffs between AI coding agents, with a live status page

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, self-hosted
Runs
Locally
Version
0.1.0
Listing updated
1 day ago

About AgentBrain Handoffs

AgentBrain Handoffs is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.

The problem it targets is delivery, not messaging: a handoff can get lost, arrive twice or land in a session that is mid-turn. The package sends each handoff as one new turn in the recipient's existing session, waits if that agent is busy, reserves an attempt before writing, and treats a lost reply as uncertain so it is observed rather than resent.

A work contract is a handoff with a title. The recipient returns a result or a blocker, and the sender closes it as accepted, needing revision or blocked, with an optional due time that triggers one non-waking reminder. The README documents a fourteen-value delivery state list, including waiting, busy, held, uncertain, returned and cancelled. Errored turns are resent a bounded number of times, and a busy agent is never interrupted.

It is a local Python package using only the standard library, with a handoffs command, a live dashboard and a stdio MCP server. A demo command runs four simulated agents (Planner, Engineer, Reviewer, Writer) on a local page and deletes its data on exit.

Install

Run in a terminal

claude mcp add agentbrain-handoffs -- docker run -i --rm ghcr.io/willykeenan/agentbrain-handoffs:0.1.0

Add to claude_desktop_config.json

{
  "mcpServers": {
    "agentbrain-handoffs": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/willykeenan/agentbrain-handoffs:0.1.0"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "agentbrain-handoffs": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/willykeenan/agentbrain-handoffs:0.1.0"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

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

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

What it does

Exactly one turn
Delivers each handoff to the addressed agent once, at the session it had when enrolled.
Never interrupts
A busy recipient keeps its turn and the handoff waits.
Bounded retries
Resends errored turns up to twice and interrupted turns once.
Uncertain state
Observes a possibly delivered write instead of resending it.
Work contracts
Handoffs with titles, returned results, sender decisions and optional reminders.
Live dashboard
Shows agent status, handoffs and a timeline of events.
Offline demo
Simulates four agents without contacting anything real.

Good for

  • Pass a task from a planning agent to an engineering agent without losing it
  • Prevent duplicate deliveries when a provider drops a reply
  • Track which handoffs are waiting, running or returned
  • Close out delegated work as accepted, revised or blocked
  • Try the delivery model locally with simulated agents

Pricing

Open source

Prices change. Check huggingface.co before you buy.

AgentBrain Handoffs FAQ

How do I try it?

Install the package from a clone and run handoffs demo, then open the local page it prints.

Will a handoff ever interrupt a running agent?

No. A busy recipient keeps its turn and the handoff waits as busy.

What happens when a reply is lost?

The attempt becomes uncertain and is reconciled by observation, never resent blindly.

What does it require?

Python 3.9 or newer and only the standard library.

Is AgentBrain Handoffs free?

Yes. AgentBrain Handoffs is open source, so you can use and self-host it for free.

How do I add AgentBrain Handoffs to Claude Code?

Run this command in your terminal: claude mcp add agentbrain-handoffs -- docker run -i --rm ghcr.io/willykeenan/agentbrain-handoffs:0.1.0

What are the best alternatives to AgentBrain Handoffs?

The closest alternatives to AgentBrain Handoffs are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

Alternatives to AgentBrain Handoffs

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ha MCP

    MCP server

    MCP server for managing and automating Home Assistant from AI assistants

    Runs locally
    • 8 tools
    • Open source
    • 7.9K GitHub stars
    • Productivity