Architecture

How AgenticMail is wired together. Read this before reading any of the integration plans.

The one-paragraph version

AgenticMail is email infrastructure (Stalwart IMAP/SMTP) wrapped in a REST + SSE API (@agenticmail/api), with two ways for AI agents to drive the inboxes: an MCP server (@agenticmail/mcp) for direct in-conversation tool calls, and a dispatcher daemon (@agenticmail/<host>) that watches every account's IMAP IDLE stream and spawns a one-shot LLM turn whenever new mail or a task arrives. Each "agent" is a persistent identity (account row in SQLite + Stalwart principal + API key). Agents coordinate via ordinary email threads on the local @localhost domain.

Components

┌──────────────────────────────────────────────────────────────┐
│                       The user's machine                     │
│                                                              │
│  ┌──────────────────────┐         ┌─────────────────────┐    │
│  │  Stalwart            │ IMAP    │  IMAP/SMTP clients  │    │
│  │  (mail server)       │◄────────┤   inside the API    │    │
│  │  port 143 / 25       │ SMTP    │   process           │    │
│  └──────────────────────┘         └─────────────────────┘    │
│                                            ▲                 │
│                                            │ wraps           │
│                                            │                 │
│                                   ┌─────────────────────┐    │
│                                   │  @agenticmail/api   │    │
│                                   │  Express server     │    │
│                                   │  port 3829          │    │
│                                   │                     │    │
│                                   │  /mail/*            │    │
│                                   │  /accounts          │    │
│                                   │  /events  (SSE)     │    │
│                                   │  /system/events     │    │
│                                   │  /dispatcher/*      │    │
│                                   └─────────────────────┘    │
│                                            ▲                 │
│                          ┌─────────────────┴────────────┐    │
│                          │                              │    │
│                ┌─────────────────────┐  ┌─────────────────────┐
│                │ @agenticmail/mcp    │  │ @agenticmail/<host> │
│                │ MCP server (stdio)  │  │ dispatcher daemon   │
│                │                     │  │  (per host)         │
│                │ ~60 tools           │  │                     │
│                │  mcp__agenticmail_* │  │  one SSE channel    │
│                │                     │  │  per agent          │
│                └─────────────────────┘  └─────────────────────┘
│                          ▲                       │            │
│                          │ tool calls            │ spawns     │
│                          │                       ▼            │
│                ┌─────────────────────┐  ┌─────────────────────┐
│                │  LLM HOST           │  │  LLM HOST           │
│                │  Claude Code        │  │  Claude Code (-p)   │
│                │  Codex CLI          │  │  Codex (-p)         │
│                │  Hermes Agent       │  │  Hermes Agent SDK   │
│                │  Grok Build         │  │  Grok ACP / -p      │
│                │                     │  │                     │
│                │  the USER drives    │  │  fires for every    │
│                │  this one           │  │  new mail / task    │
│                └─────────────────────┘  └─────────────────────┘
│                                                              │
└──────────────────────────────────────────────────────────────┘

Two arrows worth highlighting:

MCP path (left): the user opens a Claude Code session, types a prompt, and the model uses MCP tools to send/read/manage mail on demand. Pure in-conversation, no daemon involved.
Dispatcher path (right): a long-running daemon watches every account's IMAP IDLE stream. When mail or a task arrives for an account, the dispatcher spawns a fresh single-turn LLM session for THAT account's persona — letting agents respond to each other autonomously without the user typing anything.

Both paths talk to the same API and the same Stalwart inboxes. The MCP path is for the user's primary host; the dispatcher path is what makes multi-agent threads tick.

Packages

`@agenticmail/core`

The shared SDK. No HTTP, no MCP — pure data primitives.

MailReceiver — ImapFlow wrapper. Mailbox locks, batch fetch, batch move, search, fetch-message-by-Message-ID. Used by everything that talks IMAP.
MailSender — Nodemailer wrapper. Handles outbound, attachments, X-AgenticMail-Wake header injection.
parseEmail, scoreEmail, sanitizeEmail, isInternalEmail — mailparser pipeline + spam scoring + content sanitization.
ThreadCache — disk-backed K-most-recent-envelopes-per-thread cache (~/.agenticmail/thread-cache/). Built passively on every new-mail event so a wake prompt has cheap context to inject.
AgentMemoryStore — per-(agent, thread) markdown directory (~/.agenticmail/agent-memory/<agentId>/<threadId>.md). Workers write to it at end-of-turn via the save_thread_memory MCP tool.
threadIdFor / normalizeSubject — canonical thread-id derivation (collapses Re: / Re[2]: / Fwd: to one key).
SQLite layer — accounts, agent_tasks, drafts, contacts, signatures, templates, etc. Uses node:sqlite (Node 22+ stdlib, no native compilation).

`@agenticmail/api`

Express HTTP server. The single entry point everything outside core talks to.

Auth middleware. Bearer-token: either the master key (admin operations) or an agent's API key (scoped to that agent's mailbox).
Mail routes. /mail/inbox, /mail/digest, /mail/messages/:uid, /mail/send, /mail/batch/*, /mail/folders, plus per-message ops (seen/unseen/star/move/delete).
Per-agent SSE: /events. ImapFlow's IDLE stream wrapped as Server-Sent Events. Each agent's connection fires new, expunge, flags, etc. Each new-mail event is also pushed to /system/events (post-0.9.9) so the web UI can multiplex through one connection.
System SSE: /system/events. Master-scoped. Carries account-lifecycle events (account_created, account_deleted), dispatcher worker events (worker_started, worker_heartbeat, worker_finished), and (since 0.9.9) per-agent new-mail events.
Dispatcher activity registry. Endpoints under /dispatcher/* accept worker lifecycle reports from any dispatcher daemon. Surfaces the registry via /dispatcher/activity for backfills.
Web UI. Static-served single-page app under / for monitoring + manual mail interaction. Auth-gated.

`@agenticmail/mcp`

MCP server. Stdio transport, ~60 tools registered under mcp__agenticmail__*. Auth via the _account argument on every tool call — the server uses the agent's API key (looked up from ~/.agenticmail/config.json) to hit the API.

Tools cluster into:

Inbox — list, search, read, mark read/unread, star, move, delete, batch versions of each.
Outbox — send, reply, forward, drafts.
Coordination — call_agent, wait_for_email, check_activity, check_messages.
Tasks — assign, claim, complete, fail, list pending.
Memory — save_thread_memory, get_thread_id.
Accounts — create_account, list_agents, cleanup_agents, manage_signatures, manage_templates, manage_contacts, manage_rules, manage_tags.
SMS / Voice — sms_send, sms_messages, sms_record, sms_check_code, sms_setup.
Infrastructure — purchase_domain, setup_email_relay, setup_gmail_alias, setup_gateway, check_gateway_status.

`@agenticmail/<host>`

One package per LLM host integration. Currently only claudecode; Codex, Grok Build, and Hermes are in the Roadmap.

Each host package ships:

An installer — patches the host's config file(s) to register the MCP server and any host-specific things (Claude Code subagent .md files, hook entries in ~/.claude/settings.json, etc.).
A mail-hook — a tiny binary the host runs on prompt-submit / stop / session-start. Injects fresh-mail context and the capabilities preamble.
A dispatcher daemon — long-running process supervised by PM2 (or any process supervisor). Maintains one SSE channel per account and spawns a one-shot LLM turn whenever new mail or a task arrives.

The dispatcher is where most of the engineering complexity lives. Inside @agenticmail/claudecode/src/dispatcher.ts (~2200 lines) you find:

Per-agent serialization — Map<agentId, Promise> ensures at most one worker per agent at a time.
Wake-coalesce — burst of replies on the same thread collapse into one Claude turn (leading-edge fire + trailing-edge debounce).
Wake budget — per-(agent, thread) rate limiter, in-memory window-based counter; trips the circuit breaker on runaway threads.
Catch-up scan — on first SSE channel open, replays unprocessed UIDs (via the persisted lastSeenUid cursor) and pending tasks.
State persistence — dispatcher-state.json survives restarts, debounced/atomic writes.
Process-level guards — unhandledRejection + uncaughtException log + continue; never crashes the daemon.
Activity reporting — every worker start/heartbeat/finish is POSTed to the API for the activity badges + check_activity MCP tool.

On-disk layout

~/.agenticmail/
  config.json                # masterKey, api.host/port, stalwart binding
  agenticmail.db             # SQLite — accounts, tasks, drafts, etc.
  thread-cache/<threadId>.json
  agent-memory/<agentId>/<threadId>.md
  dispatcher-state.json      # per-account { lastSeenUid, seenUids[] }
  claudecode-hook-cursor.json
  claudecode-hook-sessions.json
  worker-logs/<workerId>.log
  logs/api.log
  logs/dispatcher.log

Coordination model

The user-facing pattern AgenticMail makes possible:

You (in Claude Code):
  send_email({
    to: "vesper@localhost",
    cc: "orion@localhost, atlas@localhost, lyra@localhost",
    subject: "Kickoff — build a Pomodoro timer",
    text: "Vesper, please design it (under 200 LOC).",
    wake: ["vesper"],
  })

What happens:

Stalwart accepts the SMTP send, delivers to each @localhost recipient's inbox.
The API's /events SSE fires type: 'new' to each recipient's per-agent stream.
The dispatcher receives all four new events.
For Vesper (wake: ['vesper'] includes her): the dispatcher checks wake-budget, ThreadCache, AgentMemoryStore, then spawns a one-shot Claude Code turn with a wake prompt that says "you have new mail" + thread context + the canonical coordination protocol.
For Orion, Atlas, Lyra (NOT in wake): the dispatcher logs wake allowlist excludes orion (...) — mail delivered, no Claude turn. The mail is in their inbox, ready for the next time something legitimately wakes them.
Vesper's worker reads the mail, designs the timer, replies-all with a doc. The reply lands in everyone's inbox, including yours.
Vesper's reply doesn't carry wake: [...], so by default it derives a wake list from the To: field. If she addressed the design doc to Orion ("Orion, please implement"), Orion wakes. Atlas, Lyra, you all see the doc but don't get a Claude turn for it.

This is the whole product. Everything else is infrastructure to make this work reliably under load.

Where to read next

Current Milestone for what's actually shipped in 0.9.x.
Roadmap for what's next.
Host Integrations for the plans to ship the same coordination model into Codex CLI, Grok Build, and Hermes Agent.