agent-inbox

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. Optionally integrates with agentic-mesh for encrypted P2P federation.

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. Supports WebSocket (MAP SDK) and encrypted P2P mesh (agentic-mesh) transports, configurable per-peer. 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

Agent Runtime (Claude Code, OpenAI, etc.)
  │
  Adapter (~200 lines)
  │
  └── agent-inbox (routing, threading, storage, MCP tools)
        │
        ├── Local delivery (same system)
        ├── Federation via MAP SDK (WebSocket)
        └── Federation via agentic-mesh (encrypted P2P)
              │
              MeshPeer (MAP server, FederationGateway,
                        agent discovery, hop/loop detection)

Agent Inbox can run standalone (IPC + MCP only), with a MAP server (WebSocket federation), or with an embedded agentic-mesh MeshPeer (encrypted P2P federation with full MAP protocol support).

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
INBOX_MAP_ENABLED	false	Enable MAP server connection
INBOX_MAP_SERVER	—	MAP server URL
INBOX_SQLITE_PATH	—	SQLite database path (enables persistent storage)
INBOX_HTTP_PORT	0	HTTP port for JSON-RPC endpoint

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)

# Run in MCP mode (stdio transport for Claude Code integration)
npm start -- mcp

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

Transports

Two federation transport options, configurable per-peer:

WebSocket (MAP SDK) — Traditional MAP federation. Requires a reachable MAP server endpoint.

await createAgentInbox({
  enableFederation: true,
  config: {
    federation: {
      peers: [{ systemId: "partner", url: "ws://partner:3001" }]
    }
  }
});

Mesh (agentic-mesh) — Encrypted P2P federation via Nebula/Tailscale tunnels. No central server required. Provides hop/loop detection, message buffering, and automatic agent discovery.

import { MeshPeer } from "agentic-mesh";

const peer = MeshPeer.createEmbedded({ peerId: "my-system" });
await peer.start();

await createAgentInbox({
  meshPeer: peer,
  enableFederation: true,
  config: {
    federation: {
      peers: [{ systemId: "partner", meshPeerId: "partner-peer" }]
    }
  }
});

Both transports can coexist — some peers use WebSocket, others use mesh.

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. Works with system-qualified addresses for indirect relay.

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
  mesh/
    mesh-transport.ts           MapConnection impl over agentic-mesh MessageChannel
    mesh-connector.ts           Factory for MeshTransport connections
    delivery-bridge.ts          DeliveryHandler bridge (MAP delivery → inbox storage)
    type-mapper.ts              Bidirectional MAP ↔ Inbox message translation

Testing

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

357 tests across 27 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)
• Mesh transport (MeshTransport, MeshConnector, federation-mesh integration)
• Mesh Phase 2 (DeliveryBridge, TypeMapper, MeshPeer integration)
• E2E with real agentic-mesh MeshPeer instances (bidirectional messaging, reply chains, concurrent load)

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/CLAUDE-CODE-SWARM-PROPOSAL.md — Proposal: replace claude-code-swarm's sidecar with embedded MeshPeer + agent-inbox

License

MIT