First sync
Choose a client
Section titled “Choose a client”mxrmxr starts the daemon automatically. Use the TUI, web app, CLI or an
existing agent; clients connected
to the same runtime use its shared mailbox. Start the human workflow on
Now, then follow Your day through the
five modes.
Trigger sync
Section titled “Trigger sync”mxr sync hands the work to the daemon and returns as soon as the sync has started, so you can start using mxr while the backfill runs. Leave the daemon running.
mxr sync # trigger and returnmxr sync --wait --wait-timeout-secs 900 # trigger, then wait for the account to go idlemxr sync --status # check progress at any timemxr status --watch # live daemon status--wait prints sync progress on stderr and reports detected sync failures with a non-zero exit. Failure detection depends on reading status before starting the sync; if that read fails, a later sync failure can be missed. Check mxr sync --status for the account’s last error.
Search can use only mail already synced while the backfill continues. Message bodies are stored with their envelopes; file attachments may be fetched later when you open or save them. Reaching idle ends the current sync pass for the selected account, not sync for every account or attachment caching.
--wait-timeout-secs (default 60) bounds only the wait, not the sync. If the wait expires, check status later; the sync continues.
For developers: run the daemon in the foreground
If you’re debugging the daemon itself, run it explicitly so its logs print to your terminal:
# Terminal 1: keep this runningmxr daemon --foreground
# Terminal 2: any other mxr command will use this daemonmxr statusIn normal use you don’t need this: mxr, mxr sync, and friends auto-start a background daemon if one isn’t already running.
Verify local data
Section titled “Verify local data”mxr search "label:inbox" --format idsmxr labelsmxr thread THREAD_IDWhat happens after sync finishes
Section titled “What happens after sync finishes”Current runtime behavior:
- envelopes + bodies are already in SQLite
- lexical search is already fresh for that sync batch
- semantic chunks are persisted for the changed messages
- embeddings are generated only if semantic search is enabled
Useful checks:
mxr search "deployment" --mode lexicalmxr semantic statusmxr doctor --semantic-statusContinue with the TUI
Section titled “Continue with the TUI”The TUI opens the mailbox; its sidebar also links to Now and the five modes. Use the TUI reference for current screens and keybindings. The mailbox view remains useful for arrival-order work; Your day describes the mode-based human workflow.
If something looks wrong
Section titled “If something looks wrong”If an account still has messages but all its local label associations are missing, trigger sync for that account:
mxr sync --account personal --wait --wait-timeout-secs 900mxr search "label:inbox" --account personal --format jsonFor label-capable providers, sync can refetch the account’s mail to restore associations even when other accounts have healthy labels. An ordinary poll can start one full refetch. The refetch runs through its pages and finishes even if labels remain unresolved, rather than restarting again on its final page. A later poll can retry. Recovery does not detect partial label loss or invent labels the provider cannot resolve. If labels remain missing, inspect diagnostics:
mxr doctor --checkmxr events --format jsonmxr logs --level errormxr bug-report --stdout