Mailbox Protocol

The mailbox is the file-based communication system for the monkey swarm. It enables agents to send messages to each other and the orchestrator without shared memory or a live connection.

Directory Structure

mail/
  dir/          ← agent directory (registry of active agents)
  <agent-id>/
    inbox/      ← messages received by this agent
    drafts/     ← messages composed by this agent (staging area)

Each agent has its own mailbox under mail/<agent-id>/. The orchestrator typically uses orchestrator as its ID.

Agent Directory (`mail/dir/`)

mail/dir/ is the registry of active swarm agents. Every agent writes its own entry when it starts, so other agents (and the orchestrator) can discover who is running and how to reach them.

Registering

When an agent starts, it writes a file to mail/dir/:

cat > mail/dir/<agent-id>.txt << 'EOF'
id: <agent-id>
role: <short role name>
archetype: <specialist|surveyor|researcher|planner|interfacer>
task: <one-line description>
EOF

Example — mail/dir/monkey-a3f7.txt:

id: monkey-a3f7
role: API integration specialist
archetype: specialist
task: Implement OAuth2 flow in auth module

Discovering Agents

Agents can scan mail/dir/ to find who else is in the swarm:

ls mail/dir/
cat mail/dir/monkey-a3f7.txt

Use this to find the right recipient when you need to send mail but don't know which agent ID handles a given role.

Cleanup

When an agent finishes its work, it removes its own entry:

rm mail/dir/<agent-id>.txt

The orchestrator can also clean up stale entries when a swarm run is complete.

Sending Mail

To send a message to another agent:

Write a draft — create the message in your drafts folder:
```
mail/<your-id>/drafts/01_subject-line.txt
```
The prefix number (01_) gives ordering; use sequential numbers for related messages.
Move it to the target's inbox — atomically deliver by renaming:
```
mv mail/<your-id>/drafts/01_subject-line.txt \
   mail/<target-id>/inbox/01_subject-line_<hash>.txt
```
The trailing <hash> is a short random suffix (e.g. a3f7) to avoid filename collisions.
Use mv not copy — a message is either in your drafts or in the target's inbox, never both. This avoids duplicate reads.

Receiving Mail

Check inbox at startup — read all files in mail/<your-id>/inbox/ when you begin.
Check inbox between work units — scan for new files after completing a logical step.
Process all pending mail — read every file in the inbox in filename order.
Archive after reading — move processed mail to mail/<your-id>/sent/ or leave it; the orchestrator can clean up.

Mail Format

Each .txt file is a single message with a simple format:

To: <recipient-id>
From: <sender-id>
Subject: <brief description>
---
<message body>

The --- separator distinguishes headers from the body. The body can be any plain text, code, file paths, or structured data.

Rules

Register before you work. Write your entry to mail/dir/ as one of your first actions so others can find you.
Unregister when done. Remove your mail/dir/ entry before you exit so stale agents don't linger.
Your inbox is your signal channel. The orchestrator uses it to redirect you, cancel work, or provide new context mid-run.
Keep messages short. If you have a lot to say, write a file and send a pointer in the mail.
Always move, never copy. A message in your drafts is a work-in-progress. Once moved, it's delivered.
Don't read other agents' inboxes. Only read your own. If you need to share data with another agent, send it to them — don't peek at their conversations.
Check before and between. The inbox is how you learn you've been redirected. Missing mail = missing orders.

3.8 KiB Raw Blame History