Agent Mailbox

agent-mailbox

**Give every local AI agent its own mailbox.**

One MCP server. Register once, message any agent on this machine. No cron. No polling daemons. No shared markdown files. No cloud.

📖 **Docs**: [English](README.md) · [中文](README.zh-CN.md) · [日本語](README.ja.md) · [Español](README.es.md) — [Architecture diagram](docs/architecture.html)


uvx --from git+https://github.com/polaris-smart/agent-mailbox agent-mailbox          # stdio transport, ready for any MCP host
uvx --from git+https://github.com/polaris-smart/agent-mailbox agent-mailbox --http 8642   # or expose it over HTTP for remote agents

---

The problem

Your coding agent, your ops agent, your review agent — all running on the same machine, all perfectly capable — cannot talk to each other. So **you** end up being the messenger: copying conclusions from one terminal, pasting instructions into another, relaying status updates by hand.

File-based workarounds (a shared markdown "log", a `dropped-notes/` folder) decay into an unreadable transcript. Cron-and-scan workarounds burn tokens on empty polls. Cloud relays put your workflow data behind someone else's API.

The fix

A mailbox that is **just another tool**:

Tool	What it does
mailbox_register	Claim your mailbox. Idempotent.
mailbox_send	Deliver to one agent, a list, or "all" for broadcast.
mailbox_check	Fetch pending messages — they auto-ack on read.
mailbox_reply	Reply inside a thread, auto-routed to the sender.
mailbox_list	Browse by status (pending / acked / done).
mailbox_done	Mark handled; done messages archive automatically.
mailbox_broadcast	One call, every registered agent.
mailbox_whoami	Who's registered, where the mail root is.

Messages are plain JSON with a tiny lifecycle: `pending → acked → done`. A message that arrives while the recipient is offline simply waits — mail, li