Mailbox

The mailbox is the central communication bus for all agents in a project. Every task assignment, completion report, review result, and question flows through it. Messages are persisted to a JSONL log on disk and routed in memory by the Agenties broker — giving you both durability and low latency.

Message structure

interface MailboxMessage {
  id: string;                        // "msg_<nanoid>"
  type: MessageType;                 // See message types below
  from: string;                      // "orchestrator" | "agent:<agentId>" | "user"
  to: string;                        // Routing address (see routing section)
  subject?: string;                  // Short summary
  body: string;                      // Full message content (markdown)
  metadata?: Record<string, unknown>; // Type-specific extra data
  issueId?: string;                  // Link to an issue if relevant
  agentId?: string;                  // The spawned agent this relates to
  read: boolean;
  createdAt: string;                 // ISO timestamp
}

Message types

Routing addresses

The to field of a message determines who receives it. The broker supports several routing patterns:

Persistence

JSONL log

Every message is appended to .agenties/mailbox.jsonl immediately upon creation. This file is the source of truth for the mailbox — it is never deleted while Agenties is running.

{"id":"msg_001","type":"task-assigned","from":"orchestrator","to":"agent:ag_x1","body":"...","read":true,"createdAt":"2026-05-10T14:00:00Z"}
{"id":"msg_002","type":"task-done","from":"agent:ag_x1","to":"orchestrator","body":"...","read":false,"createdAt":"2026-05-10T14:04:32Z"}
{"id":"msg_003","type":"status","from":"agent:ag_x2","to":"broadcast","body":"Running tests...","read":false,"createdAt":"2026-05-10T14:04:45Z"}

Retention policy

The mailbox retains messages for 7 days or up to 5,000 messages, whichever limit is reached first. Older messages are trimmed from the tail of the JSONL file on startup. Read messages older than 24 hours are trimmed first.

In-memory broker

The Agenties main process runs an in-memory message broker that is populated from the JSONL log on startup. New messages are pushed to the broker and appended to disk simultaneously. The broker is used for:

MCP tools

read_messages

read_messages({
  to?: string;         // Filter by recipient (defaults to caller's agentId)
  since?: string;      // ISO timestamp — only return messages after this time
  unreadOnly?: boolean; // Default: true
  limit?: number;      // Max messages to return (default: 50)
})

Agents typically call read_messages at the start of every turn with unreadOnly: true. The orchestrator calls it on every wake to process all pending results.

send_message

send_message({
  type: MessageType;
  to: string;           // Routing address
  subject?: string;
  body: string;
  metadata?: Record<string, unknown>;
  issueId?: string;
})

mark_read

mark_read({
  messageIds: string[];  // IDs to mark as read
  // OR
  all?: boolean;         // Mark all messages to this agent as read
})

Auto-trigger behaviour

The orchestrator auto-wake is one of the most powerful features of the mailbox system. When any of the following message types arrive in the broker, the orchestrator is woken automatically without any user action:

This creates a fully autonomous loop: you can assign a complex goal to the orchestrator, then step away. Agents execute, report back, the orchestrator re-plans, spawns more agents, and so on — until the goal is met or a blocking question requires your input.