Agent Inbox

A MAP-native message router for multi-agent systems. Provides structured inbox/outbox semantics, message threading, delivery tracking, and cross-system federation on top of the Multi-Agent Protocol transport layer.

Built to work with claude-code-swarm and any MAP-compatible agent framework.

What it does

• Message routing — Send messages between agents with to, cc, bcc semantics. Messages are stored in per-agent inboxes with delivery and read tracking.
• Threading — Messages can be grouped by thread_tag and linked via in_reply_to for conversation threading.
• Traceability — Auto-creates conversations, turns, and threads from messaging events following MAP's mail conventions.
• Federation — Route messages across independent systems via MAP federation. Supports configurable routing strategies (table, broadcast, hierarchical).
• Multiple interfaces — IPC (UNIX socket), MCP tools (stdio), MAP JSON-RPC, and event-based push via inbox.message events.

Architecture

Claude Code Session
  |
  Plugin (map-hook.mjs)
  |
  +-- spawn/done/trajectory --> MAP Sidecar (lifecycle)
  |
  +-- send/emit (messaging) --> Agent Inbox (routing + storage)
                                  |
                                  +-- Local delivery (same system)
                                  +-- Federation (cross-system via MAP)

Agent Inbox runs as an independent service alongside the MAP sidecar. The plugin dispatches messaging commands to Agent Inbox and lifecycle commands to the sidecar.

Quick start

npm install
npm run build
npm start

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | INBOX_SOCKET_PATH | ~/.claude/agent-inbox/inbox.sock | IPC socket path | | INBOX_SCOPE | default | Default message scope | | INBOX_SYSTEM_ID | auto-generated | System identity for federation | | MAP_SERVER_URL | — | MAP server URL (optional) | | MAP_AGENT_NAME | agent-inbox | Agent name for MAP connection |

As an MCP tool server

Agent Inbox exposes 4 MCP tools that agents can call directly:

| Tool | Description | |------|-------------| | send_message | Send a message to one or more agents (supports replies via inReplyTo) | | check_inbox | Check an agent's inbox for unread messages (auto-registers the agent) | | read_thread | Read all messages in a thread by threadTag | | list_agents | List registered agents (local and optionally federated) |

IPC protocol

NDJSON over UNIX socket. Commands:

{"action": "send", "from": "alice", "to": "bob", "payload": "Hello"}
{"action": "notify", "event": {"type": "agent.spawn", "agent": {...}}}
{"action": "ping"}

MAP JSON-RPC

When connected to a MAP server, Agent Inbox registers JSON-RPC methods:

• mail/send — Send a message
• mail/inbox — Check inbox
• mail/thread — Read a thread
• mail/ack — Acknowledge a message
• mail/search — Full-text search (requires SQLite storage)

Federation

Agents on different systems can message each other using agent@system addressing:

alice@system-1  -->  bob@system-2

Configuration

Federation peers are configured explicitly:

await inbox.federate({
  systemId: "partner-system",
  url: "ws://partner.example.com:3001",
  exposure: { agents: "all" },
});

Routing strategies

| Strategy | Behavior | |----------|----------| | table (default) | In-memory routing table populated from peer exposure data. TTL-based expiry. | | broadcast | Forward to all connected peers. First responder wins. | | hierarchical | Local table first, then delegate to upstream hubs. |

Trust

Federation connections are gated by an allow-list. Only systems in allowedServers can establish federation links.

Delivery queue

Messages to offline peers are queued with configurable TTL, overflow policy, and retry strategy. Queues flush automatically on reconnect.

Storage

Two storage backends:

• InMemoryStorage — Default. Fast, no dependencies. Data lost on restart.
• SQLiteStorage — Persistent storage with FTS5 full-text search. Requires better-sqlite3.

Project structure

src/
  index.ts                      Entry point — wires all components
  types.ts                      Core type definitions
  storage/
    interface.ts                Storage interface
    memory.ts                   In-memory implementation
    sqlite.ts                   SQLite implementation (persistent + FTS5)
  router/
    message-router.ts           Message routing: resolve recipients, local vs remote
  federation/
    connection-manager.ts       MAP connections + federation peer management
    routing-engine.ts           Configurable routing (table/broadcast/hierarchical)
    delivery-queue.ts           Offline message queue with TTL + retry
    address.ts                  Parse/resolve agent@system addresses
    trust.ts                    Federation trust policies (allow-list)
  registry/
    warm-registry.ts            Agent lifecycle: active/away/expired + TTL
  traceability/
    traceability.ts             Auto-create conversations/turns/threads
  ipc/
    ipc-server.ts               UNIX socket server (NDJSON protocol)
  map/
    map-client.ts               MAP SDK connection wrapper
  mcp/
    mcp-server.ts               MCP tool server (stdio transport)
  jsonrpc/
    mail-server.ts              MAP JSON-RPC mail methods
  push/
    notifier.ts                 Inbox file writes + inbox.message event emission

Testing

npm test              # Run all tests
npm run test:watch    # Watch mode

256 tests across 18 test files covering:

• Storage (in-memory + SQLite)
• Message routing and content normalization
• Traceability (auto-conversation/thread creation)
• IPC server (NDJSON protocol, concurrent clients)
• Federation (connection manager, routing engine, delivery queue, address parsing, trust)
• Federation integration (end-to-end multi-system scenarios)
• SDK integration (two-system tests with in-process mock MAP server)
• MAP JSON-RPC mail methods
• Warm agent registry lifecycle
• Push model (inbox.message events + inbox file writes)

Development

npm run dev           # TypeScript watch mode
npm test              # Run tests
npm run build         # Production build

Requires Node.js >= 18.

Further reading

• docs/DESIGN.md — Detailed architecture and design decisions
• docs/PLAN.md — Implementation plan and phasing

License

MIT