Skip to content

Architecture

mxr is a local mail runtime. Its clients share daemon-backed mail operations over a local store, search index and provider adapters.

TUI / CLI / web / MCP / scripts
|
v
daemon
/ | \
SQLite Tantivy provider adapters
canonical rebuildable |
v
mail providers

The daemon coordinates shared local mail state and operations. SQLite is canonical; Tantivy is rebuildable from it. Provider adapters map provider mail into mxr’s internal model and handle provider I/O. Clients can reuse daemon operations without duplicating provider behavior, while exposing different capabilities and authority.

mxr keeps one flat IPC wire format, but the contract is easier to maintain if you sort it mentally into four buckets:

  1. core-mail
  2. mxr-platform
  3. admin-maintenance
  4. client-specific

Only the first three belong in daemon IPC.

  • core-mail: search, sync, envelopes, bodies, threads, labels, drafts, send, mutations, attachments, export
  • mxr-platform: accounts, rules, saved searches, subscriptions, semantic runtime
  • admin-maintenance: status, events, logs, doctor, bug reports, local reset, repair/inspection
  • client-specific: sidebar grouping, pane state, right-rail shaping, selection state; keep this in TUI/web/CLI layers

The daemon serves reusable truth and workflows, not screen payloads.

Mail should stay useful when the network is flaky, when you want to script against it, and when you do not want another hosted layer in the middle.

The TUI should not be the whole system. Background sync, indexing, snooze, and rules should keep running without an open UI.

Gmail labels, IMAP folders, flags, drafts, and bodies all have to meet the same internal model. That is what keeps the rest of the codebase sane.

Search is not a fallback. It is how power users move through a mailbox. That is why mxr uses Tantivy and saved searches instead of treating search as an afterthought.

Compose opens the editor you already use. mxr handles parsing, reply headers, markdown-to-multipart conversion, and sending.

  1. Local-first
  2. Provider-agnostic internal model
  3. Daemon-backed architecture
  4. $EDITOR for writing
  5. Fast search is first-class
  6. Saved searches are a core primitive
  7. Rules are deterministic first
  8. Shell hooks over plugin systems
  9. Adapters are swappable
  10. Correctness beats cleverness

Stored asks share one answer across clients

Section titled “Stored asks share one answer across clients”

The deterministic asks facet covers received and sent mail. It stores who acts, what they were asked to do, document state and authored source spans. To do, reply turns, waits and relationship commitments project that answer. Home placement remains an inbound-only facet; both facets commit under the same thread-generation check. Missing or stale asks stay pending. No model decides this facet.

Inspect the stored answer and a task projected from it:

Terminal window
mxr modes why MESSAGE_ID --format json
mxr todo why TODO_ID --format json

An answer is current only for its account, classifier policy, observed input generation and context. Owned addresses, actual timezone rules and account receiver-trust settings also participate in asks validity. Changing those inputs schedules reconciliation. An unchanged daemon restart retains settled answers without invalidating the whole mailbox.

Saving an answer also persists its task-projection retry ticket. Acknowledging that ticket checks the exact generation and fingerprint, so an older worker cannot consume newer work. Evaluation distinguishes unsettled projection from a settled answer with a missing task. Current-answer reads do not run a replacement judge.

Task corrections retain their reason and before/after state separately from the authored source quote. A later accepted promise date can update the date and its derived timing while preserving a corrected title or kind. If you edited the due date directly on the task, that authority blocks the entire promise-date update, including its derived timing.

Lists read compact facts; detail keeps the evidence

Section titled “Lists read compact facts; detail keeps the evidence”

Compare the list and detail surfaces:

Terminal window
mxr messages list --turn all --format json
mxr messages person samir@launchpad.example --format json
mxr modes why MESSAGE_ID --format json

Lists use compact, rebuildable asks and thread facts, so navigation does not decode every stored body or full classification explanation. Opening a conversation or inspecting a placement reads the full source evidence. List previews read a bounded set of stored body text and skip attachment metadata.

Before it reuses thread facts, mxr checks the account, policy, input and view revisions, context and time boundaries. Read flags, inbox membership and facet writes invalidate thread facts even when the source generation is unchanged. Turns, Done state, people links, contact facts, ranking and filters are always composed live.

A separate short-lived daemon cache reuses completed mode responses. That cache does not hold these facts. For measurement and isolated invalidation checks, use the repository’s local mail-view procedure.