agent-postbox

Verifiable handoffs for MCP agents. agent-postbox makes agent handoffs over GitHub verifiable – with read-back and evidence instead of bare status messages.

AI coworkers collaborate through GitHub Issues and pull requests – with bounded writes, receipts and four-eyes review.

You already have a durable, auditable, human-readable coordination system: your GitHub repository. agent-postbox turns it into a mailbox for AI agents, so they can hand work to each other, report results and review each other's pull requests, while every write stays small, verified and attributable, and every decision stays with a human.

It is a small Model Context Protocol server (stdio or Streamable HTTP) plus a CLI. Zero runtime dependencies.

human ──opens issue──▶  #12  [to:builder]
builder ── inbox ─────▶ claims (claimed:builder), works, opens PR #13 [to:reviewer]
reviewer ─ review ────▶ REQUEST_CHANGES on #13 @ head commit (cannot review its own PR)
builder ── comment ───▶ evidence: tests, output, links
human ───────────────▶ merges. Agents cannot merge, close, or set authority labels.

A shared inbox delivers a message. agent-postbox proves the handoff happened – read-back of every write, an acknowledgement bound to the exact text the agent read, no self-review, and a signed evidence log you can verify.

Release: v0.2.1 · For: developers running several coding agents (Claude Code, Codex, Cursor, …) on one GitHub repo · Zero runtime dependencies.

Try it in 30 seconds

No GitHub account, token or network needed – the demo runs two agents against an in-memory GitHub with synthetic data:

git clone https://github.com/Aethelgard-Systems/agent-postbox.git
cd agent-postbox
npm run demo

Windows PowerShell blocks npm with “running scripts is disabled on this system”? Use npm.cmd run demo or node examples/offline-demo/demo.mjs instead – same demo, no policy change needed.

You will see a builder and a reviewer hand work to each other, a lost network response reconciled instead of posted twice, and three unsafe actions refused (self-review, a human-only label, a token in a comment). Details and limits: examples/offline-demo.

npm run demo:handoff shows the v0.2 flow: a planner hands a task to a builder, the builder's acknowledgement is bound to the text it read (an edited handoff is refused until re-read), and the signed evidence log is verified – then tampered with and caught.

Why

Multi-agent setups usually fail in boring ways: an agent claims it posted something it did not, posts the same thing twice after a timeout, approves its own work, treats text in an issue as an order, or leaks a token into a comment. agent-postbox addresses exactly those failure modes and nothing else.

... View full README on GitHub