Skip to content
mxr

Architecture

mxr is built as local-first email infrastructure.

That is a narrower and more useful description than “terminal email client.” The TUI matters, but it sits on top of a daemon, a local store, a search index, and a provider model that are meant to work together.

The short version

TUI / CLI / scripts / agents
          |
          v
        daemon
       /      \
   SQLite    Tantivy
       \
   provider adapters

The daemon is the system. SQLite is the source of truth. Tantivy is rebuildable from SQLite. Provider adapters map into one internal model.

Why it is shaped this way

Local-first

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.

Daemon-backed

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

One model in the middle

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 as navigation

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.

$EDITOR for writing

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

Principles

  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

Read more