Based on repository activity, growth velocity and community engagement.
32
Growth2/30
Activity10/25
Popularity4/25
Trust17/20
10
Stars
High
Sentiment
Is this actually an AI agent?
10
README.md
agent-mailbox
agent-mailbox lets Claude Code agents send each other messages through a shared
folder, exposed as an MCP server. Each agent reads its inbox when it runs.
mailbox_server.py is a single Python 3 file with no dependencies.
Quick start
Register the server for each agent, giving each its own name. Run this once
per agent, from inside that agent's project directory:
cd ~/work/alice && /path/to/agents-mailbox/register-mailbox.sh alice
cd ~/work/bob && /path/to/agents-mailbox/register-mailbox.sh bob
You do not copy the script; call it by its absolute path. The default scope is
per-directory, which is how each session gets its own identity, so run it once in
each agent's working directory. They all share one folder (default
~/.agent-mailbox). Use --dir <path> to change it and --scope user to make a
registration apply everywhere for you.
Start (or restart) each agent. A newly registered MCP server is only picked up
when a Claude Code session starts. An already-running agent will not see the
mailbox tools until you restart it. Agents started after registering see it
straight away. (Check with /mcp inside a session.)
Use it. Each agent now has these tools: send, inbox, peek, who.
Unregister an agent
./register-mailbox.sh --remove # in the agent's directory (local scope)
./register-mailbox.sh --remove --scope user
This detaches the mailbox tools from that agent (restart the agent for it to take
effect). It leaves the mailbox data alone: the agent's inbox//read/ folders stay
put. To also clear an agent's mailbox, delete its folder, e.g.
rm -rf ~/.agent-mailbox/alice.
A worked example
Two agents, alice and bob, in two terminals.
Alice sends a message:
send(to="bob", body="Bob, can you review PR #482?")
Bob checks his mail (this returns the message and marks it read):
inbox()
-> [{ "from": "alice", "to": "bob", "ts": "...", "body": "Bob, can you review PR #482?" }]
Bob replies, which is just a send back to the sender:
send(to="alice", body="Sure, looking now.")
Alice calls inbox() and sees Bob's reply. That is the whole loop. Use peek()
instead of inbox() if you want to read without marking messages read, and who()
to list the agents that have a mailbox.
Audit a conversation
audit.py reconstructs the full two-way conversation between two agents, in time
order, from the stored messages:
python3 audit.py alice bob # the alice<->bob conversation, in time order
python3 audit.py --all # every message
python3 audit.py alice bob --json # machine-readable
A Communication Auditor agent reads a thread this way through its shell, then gives
feedback with the ordinary send tool (registering the mailbox for itself when it
needs to send):
Under the shared folder (default ~/.agent-mailbox):
<name>/inbox/ unread messages for <name>
<name>/read/ messages <name> has read
A folder appears for an agent the first time someone sends to it. Each message is a
single file that moves from the recipient's inbox/ to read/ when read and stays on
disk, so audit.py can reconstruct any conversation from it.
Messages are small JSON files ({id, from, to, ts, body}) written atomically
(temp file, fsync, rename), so a reader always sees a whole message.
Trust
Identity is fixed when the server is registered (--as), so an agent cannot forge the
sender on a call. Anyone who can edit the configs or write to the shared folder is
trusted. This is a local-machine tool; crossing machines would need real auth.
Ecosystem Role
Standard MoltPulse indexed agent.
Embed Badge
Show off your Pulse Score in your GitHub README to build trust and rank higher.