Agent Postbox

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.

Non-goals

Not an agent framework, not a runtime, no database, no dashboard, no worktree orchestration, no role model. Bring your own agents; agent-postbox is only the mailbox.

Tools

The complete tool list costs under 4,500 characters of model context (tested).

Quick start

1. One identity per agent. Each agent needs its own GitHub identity so that authorship and four-eyes review are real – a dedicated machine account with a fine-grained personal access token limited to one repository (*Issues: read/write*, *Pull requests: read/write*, *Metadata: read*), or a GitHub App installation token. Classic tokens are refused by default.
2. Install (Node.js ≥ 20):

   npm install -g github:Aethelgard-Systems/agent-postbox

1. Configure – agent-postbox.config.json:

   {

"repository": "example-org/example-repo", "agent": "builder", "tokenEnv": "AGENT_POSTBOX_TOKEN", "allowedLabels": ["needs-review", "blocked", "question"], "protectedLabels": ["approved", "decision:*"], "limits": { "writesPerDay": 50, "proposalsPerDay": 5 } }

4. **Check** without writing anything:

   AGENT_POSTBOX_TOKEN=... agent-postbox doctor

1. Connect your MCP client (example for clients using the common mcpServers format). For clients that speak Streamable HTTP, run agent-postbox serve --transport http --port 8471 instead and point them at http://127.0.0.1:8471/mcp (other hosts need AGENT_POSTBOX_HTTP_TOKEN):

   {

"mcpServers": { "agent-postbox": { "command": "agent-postbox", "args": ["serve", "--config", "/path/to/agent-postbox.config.json"], "env": { "AGENT_POSTBOX_TOKEN": " " } } } }

6. Copy [`templates/AGENTS.md`](templates/AGENTS.md) and [`templates/pull_request_template.md`](templates/pull_request_template.md) into your repository so agents and humans share one protocol.

Step-by-step setup: docs/getting-started.md. A walk-through with two agents reviewing each other is in examples/two-agent-review.

Configuration

CLI

agent-postbox doctor | inbox | read <n> | comment <n> --body ... | label <n> --add a --remove b

agent-postbox propose --title ... --body-file ... | review --event approve|request-changes|comment --body ... agent-postbox handoff create --to --title ... --body ... [--acceptance "a|b"] | handoff read agent-postbox handoff ack --read-sha256 --result done|partial|blocked|declined [--evidence "a|b"] agent-postbox receipts list | receipts resolve --as confirmed|failed agent-postbox evidence verify | evidence key agent-postbox serve [--transport stdio|http] [--host 127.0.0.1] [--port 8471]

All output is JSON. Refusals exit with code 2 and a stable error code (POLICY, SECRET, LIMIT, SELF_REVIEW, UNKNOWN_OUTCOME, READBACK_MISMATCH, …).

Evidence log (v0.2)

Next to the receipts file, agent-postbox keeps .evidence.jsonl: one line per receipt state change, hash-chained and signed with the agent's Ed25519 key. It holds keys, kinds, states, read-back verdicts and hashes – never bodies, titles or tokens. agent-postbox evidence verify recomputes the chain and reports any modified, removed, reordered, forged or truncated line. The format is documented in docs/evidence-format.md and shared with companion tools, so one verifier works for all of them.

Known limits (v0.2)

• An identical comment text on the same issue is posted only once (replay protection); add context to make a new comment distinct.
• Duplicate-title checks and reconciliation scan up to 1,000 items. GitHub's issue lists can lag a few seconds behind writes: an agent's own duplicates are caught locally, but two different agents proposing the same title within seconds may both succeed.
• Adding a to: label creates that label in the repository if it does not exist yet.
• Reviews and comments are not edited or deleted by agent-postbox – by design.
• serve over stdio starts even without config or token so clients can list the tools; each tool call then returns CONFIG/TOKEN until it is set up. The HTTP transport refuses to start instead.
• When the MCP server and the CLI share a receipt file, a lock conflict can pause the server for up to 5 seconds, and concurrent processes may exceed a daily limit by a few writes.
• The HTTP transport is stateless JSON (no SSE, no sessions, no server-initiated messages) and has no TLS; put it behind your own reverse proxy when it leaves the machine. Browsers are kept out by design (JSON content type required, Host must name the server, Origin refused unless listed in `AGENT_POSTBOX_HTTP_ORI