What it does
agent-postbox lets AI agents hand tasks to each other, report results and review each other's pull requests through a GitHub repository. Each write is fetched again and compared before it counts as done, and an acknowledgement is bound to the exact text the agent read. Write receipts record attempts and confirmations, and an unknown outcome is reconciled only when GitHub shows the same write from the agent's own identity. Agents cannot approve their own pull requests, protected labels such as approved and decision:* are reserved for humans, and all content read from GitHub is marked as untrusted. The server exposes a fixed set of tools (inbox, read, comment, label, propose, review and three handoff tools) and an allowlist of endpoints that excludes merge, close, delete, body edits, settings and code access. It also applies daily limits to writes and proposals, and a best-effort secret filter to titles and bodies.
It suits a setup where several coding agents, such as Claude Code, Codex or Cursor, work on one GitHub repository and need a record of who handed what to whom and what was verified. Handoffs carry acceptance criteria, and the evidence log is hash-chained and Ed25519-signed, so later edits, gaps or truncation can be detected with the verify command. The project does not provide an agent framework, runtime, database, dashboard or role model; it covers only the mailbox.
Running it requires Node.js 20 or later and a GitHub identity for each agent, ideally a dedicated machine account with a fine-grained token limited to one repository, or a GitHub App installation token. The server runs over stdio or Streamable HTTP, and a configuration file defines the agents and their settings. An offline demo runs two agents against an in-memory GitHub with synthetic data and needs no account or token. Copying the provided AGENTS.md and pull request template into the repository lets agents and humans follow one protocol.
Limitations and requirements
Each agent needs its own GitHub identity; classic personal access tokens are refused by default. A fine-grained token needs Issues read/write, Pull requests read/write and Metadata read on a single repository. Node.js 20 or later is required. Other hosts connecting over Streamable HTTP need the AGENT_POSTBOX_HTTP_TOKEN setting. The secret filter is best effort. An unknown write outcome stays blocked until a human resolves it. Protected labels can only be set by humans.
Safety
Our team has not reviewed this resource. Only automated rules checked it; resources with high-risk signals are not published. These are signals, not a guarantee that installing it is safe. Try it in a sandbox project first.
- Runs code or changes an assistant's behaviour
Sources
- Official MCP Registry first seen 13 Nov 2026 · last seen 13 Nov 2026 · its page on the source
io.github.Aethelgard-Systems/agent-postbox
Verifiable agent handoffs over GitHub Issues and PRs: bounded writes, read-back, evidence log.
v0.2.1As shown on registry.modelcontextprotocol.io when we last read it