Agent Postbox

[agent-postbox – AI agent handoffs with receipts: Agent A hands work through the postbox to Agent B, every write is read back, self-review is blocked, a human approves the merge.]

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, linkshuman ───────────────▶ 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.gitcd agent-postboxnpm 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):
   sh

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

3. Configure – agent-postbox.config.json:
   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:
   sh

   AGENT_POSTBOX_TOKEN=... agent-postbox doctor

5. 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):
   json

   {  "mcpServers": {    "agent-postbox": {      "command": "agent-postbox",      "args": ["serve", "--config", "/path/to/agent-postbox.config.json"],      "env": { "AGENT_POSTBOX_TOKEN": "<this agent's token>" }    }  }}

6. Copy templates/AGENTS.md and 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 bagent-postbox propose --title ... --body-file ... | review <n> --event approve|request-changes|comment --body ...agent-postbox handoff create --to <agent> --title ... --body ... [--acceptance "a|b"] | handoff read <n>agent-postbox handoff ack <n> --read-sha256 <hex> --result done|partial|blocked|declined [--evidence "a|b"]agent-postbox receipts list | receipts resolve <key> --as confirmed|failedagent-postbox evidence verify | evidence keyagent-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 <receipts>.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:<agent> 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_ORIGINS).
• The evidence log proves what was written to it, not what bypassed it; see docs/evidence-format.md "What it does not prove". Truncation at the end is detected through the signed .head sidecar – if the sidecar is deleted, evidence verify warns instead of passing cleanly.

Security model

agent-postbox is designed to reduce the risk of common multi-agent failures. It is not a sandbox.

• The token is the real boundary. agent-postbox cannot stop someone who has the token from calling GitHub directly. Use one narrowly scoped token per agent and protect main with branch protection and required reviews, so merging stays human.
• Four-eyes depends on separate identities. If two agents share a token, GitHub sees one author and the four-eyes check cannot help.
• The secret filter is best effort. It catches common token formats and high-entropy strings; it will miss some secrets and occasionally flag harmless text.
• Untrusted content stays untrusted. agent-postbox labels everything it reads as data. Whether your agent respects that depends on your agent.
• Receipts are a local hint, GitHub is the truth. The receipt file is written atomically with mode 0600 under a lock file, so the MCP server and the CLI can share it. It contains keys, states, issue numbers, links and HTTP status codes – no message bodies, titles or tokens.
• Markers are invisible, not secret. Each write carries an HTML comment marker. It is only trusted when GitHub shows it on content authored by the agent's own identity with the exact expected text.
• Limits are local. Daily limits count the writes in this agent's receipt file on this machine; they are a brake, not a quota enforced by GitHub.
• No telemetry, no hosted service. agent-postbox talks only to api.github.com with the token you provide.

Please report vulnerabilities as described in SECURITY.md.

See the threat model for actors, trust boundaries, controls and remaining risks.

AI-assisted development

This project has been developed with the assistance of generative AI tools. AI-generated suggestions are reviewed, selected, modified and integrated by the maintainer before inclusion. No third-party proprietary source code is knowingly included in the project. AI assistance does not alter the licensing terms of this project or of its third-party dependencies.

Disclaimer

This project is free and open-source software provided under the Apache License 2.0.

The software is provided on an "AS IS" basis. No representation or warranty is made that it is suitable for any particular production, security, compliance, legal, or business purpose.

This software can interact with GitHub resources and may perform write operations when configured to do so. Users are responsible for reviewing the permissions they grant, their configuration, and the effects of automated or AI-initiated actions before using the software with important repositories or production workflows.

Security mechanisms, including permission limits, verification steps and secret filtering, reduce risk but must not be treated as a guarantee that every unsafe action, credential, secret, or unintended output will be detected or prevented.

Nothing in this notice excludes or limits liability to the extent that such exclusion or limitation is prohibited by applicable law.

License

Apache License 2.0. Copyright 2026 Marco Gernand. Contributions are welcome under the Developer Certificate of Origin.