Diagnose mxr fast
When something feels off — sync hasn’t run, a draft vanished, a rule misfired — mxr gives you four lenses on the same daemon: status, logs, events, and activity. They all live one keystroke or one URL away.
Health check first
Section titled “Health check first”Start broad. status shows the daemon’s current view; doctor checks the deeper invariants.
# Single snapshotmxr status
# Watch it livemxr status --watch
# Deep check (rebuild advisories, store stats, index freshness)mxr doctor --check --format jsonWhat you get: a single object with daemon uptime, account sync status, lexical/semantic index freshness, and any active findings.
mxr doctor --check exits 0 only when the report carries no Error-severity finding, so it works as a CI or cron gate:
mxr doctor --check --format json >/tmp/mxr-doctor.json \ || jq '.findings[] | select(.severity == "error")' /tmp/mxr-doctor.jsonDiagnostics for a selected daemon
Section titled “Diagnostics for a selected daemon”mxr status and mxr doctor --check, --store-stats, or --index-stats use the daemon selected by MXR_DAEMON_ADDR. For an explicit target, JSON keeps ownership clear: daemon_target identifies the selection, client_local contains paths on the CLI machine, and doctor places the daemon report or statistics under daemon. Any remediation and next-step commands in the daemon report, including table output, must be run on the selected daemon host.
MXR_DAEMON_ADDR="cmd://ssh -T host mxr daemon dial-stdio" mxr status --format jsonMXR_DAEMON_ADDR="cmd://ssh -T host mxr daemon dial-stdio" mxr doctor --check --format jsonIf that target cannot be reached, the diagnostic command fails without switching to or starting the local default daemon. Connection metadata and client-generated connection errors hide cmd:// arguments. mxr doctor --reindex operates on the local profile. Run it on the daemon host with MXR_DAEMON_ADDR unset and the intended MXR_INSTANCE or MXR_CONFIG_DIR/MXR_DATA_DIR settings.
Is my mail current?
Section titled “Is my mail current?”mxr status --freshness answers the quick “is new mail reaching me?” check: when the newest message arrived (any mailbox, any mode), each account’s last good sync, the last sync error with its kind and retry time, and the last arrivals with the mode each one went to.
mxr status --freshness# Latest mail 5m ago (09:37)# Sync: Gmail paused: rate limited, retrying 09:50# Last arrivals:# 09:37 GitHub Build passed → Updates · automated
mxr status --freshness --account work --limit 20 --format jsonWith several accounts, the default scope shows the freshest mail and the worst sync state. The web app shows the same two signals in its status bar on every page, and the TUI shows them in its status line. The bridge serves it at GET /api/v1/mail/freshness.
Is sync slow, or failing?
Section titled “Is sync slow, or failing?”mxr doctor summarises each account’s last 50 sync runs, so you can tell slow syncs from failing ones without opening the database. Unfinished runs are counted separately and never feed the durations.
mxr doctor --format table# Sync history (newest 50 syncs per account):# Work: 50 syncs, 7 failed, 1 unfinished# duration: median 7.0s, slowest 16.0s, latest 15.0s, trend slower# recurring errors:# 7x IMAP timeout after <n> seconds fetching uid <n> (last 2026-10-21T23:25:09+00:00)# Personal: 3 syncs, 1 failed, 0 unfinished# duration: median 4.0s, slowest 5.0s, latest 5.0s# recurring errors: none- Trend compares the median of the newest 10 finished syncs with the 40 before them. It reads
slowerorfasteronly when the median moves by at least 50% and by at least 5 seconds. With fewer than five finished syncs in either window, the trend is left out. - Recurring errors group failures whose messages differ only in ids, numbers, timestamps, quoted values or email addresses. A message counts once it has appeared twice. The list shows at most five groups, and each message is clipped to 160 characters.
The JSON report carries the same data under sync_history, one object per account.
When the daemon says degraded
Section titled “When the daemon says degraded”mxr status reads its account and message counts out of SQLite. A large sync can saturate the reader pool, and rather than block, the daemon answers with degraded: true and no snapshot. That is “the daemon did not say”, not “there are no accounts”:
mxr status --format json | jq '{degraded, accounts, total_messages}'The table output prints unknown for the fields it has no reading for, instead of a zero that reads like an empty mailbox. Poll again once the sync settles — nothing needs fixing. The version, PID, and feature-health fields are always a real reading.
Why a second mxr now is instant
Section titled “Why a second mxr now is instant”The daemon reuses completed Now, rail, Messages, Updates and Reading-edition responses. It keeps recently read views and serves one only while these checks hold:
- Anything you change through mxr (a done, a move, a reply) makes the next read rebuild first.
- New mail and other stored changes do the same. Log, sync-bookkeeping and index writes don’t count.
- A view older than a minute, or built before the current hour, is rebuilt first, because the views word time (“due soon”, evening, today).
The background refresher keeps views read in the last five minutes. It renews each one ten seconds before its one-minute expiry, so the web app’s one-minute poll finds a ready view. After a stored change, the refresher waits at least five seconds between rebuilds of a view. It drops idle views. generated_at in the JSON says when a response was built.
A rebuild reuses stored asks and history facts when they are still valid. Rebuild cost depends on the view, the mailbox, startup work and which facts are ready. A cached repeat is not a cold-read measurement. See the architecture and slow-view troubleshooting.
A read that can record something always runs. mxr reading counts as a visit unless activity tracking is off or paused. mxr reading edition --peek never counts as a visit.
To watch the rebuilds, set level = "debug" under [logging] in config.toml, restart the daemon, and search the log:
mxr logs --no-follow --search 'mode view refreshed' --since 10mRead past logs without tail -f
Section titled “Read past logs without tail -f”Use mxr logs to read the active file and retained mxr archives on this machine.
It accepts --level, --search, --limit, and --since together.
# Last 200 warn-or-error lines in the last hourmxr logs --no-follow --level warn --since 1h --limit 200
# Past errors mentioning Gmailmxr logs --no-follow --level error --search 'gmail' --since 24h
# Stream JSON to jq for ad-hoc analyticsmxr logs --format jsonl --limit 1000 | jq -r 'select(.level=="ERROR")'What you get: the most recent --limit lines that match your filter. With --format json|jsonl, each line becomes { timestamp, level, message, raw } for piping.
--level warn includes WARN and ERROR, using the record’s actual level rather
than words in its message. --since accepts RFC 3339 or durations such as 1h;
records without a parseable timestamp cannot pass that time filter. Legacy
space-delimited logs remain readable. --limit is the initial matching tail,
from 1 to 10,000 lines (default 200), not a limit on later follow output. Reading
keeps only that tail in memory, not every matching line. Legacy records over
64 KiB are skipped.
Without --no-follow, the command polls every 500 ms. It tracks file identity
and complete-line offsets through rotation, replacement and daemon restart.
Partial trailing lines wait for a newline; retained old lines are not replayed
after a rename. Logs already removed by retention between polls cannot be
recovered. Read snapshots may briefly keep a rotated file open until their scan
finishes; daemon writers do not retain an old active-file handle.
When you want the file open in $EDITOR:
mxr logs --no-follow --limit 1000 > /tmp/mxr.log && $EDITOR /tmp/mxr.logAutomatic history retention
Section titled “Automatic history retention”The daemon prunes event_log and sync_log once a day, starting about a minute
after startup. It reads logging.event_retention_days (default 90) on each pass,
so mxr config set logging.event_retention_days <n> applies without a restart.
0 keeps everything. Rows older than the cutoff are deleted, except:
- the newest “Lexical index rebuilt” event, which
mxr doctorreads for the index’s last rebuild time; - each account’s newest 50
sync_logrows, so a rarely syncing account keeps the history doctor shows.
Unsubscribe receipts are in their own table and are never pruned. The daemon logs row counts only, not contents.
Check the setting the daemon will use:
mxr doctor --format table | grep '^History:'What you get: History: kept 90 days, pruned daily (sync keeps the newest 50 rows per account),
or kept forever (automatic prune off) when event_retention_days is 0. The
JSON report carries the number as history_retention_days.
Bound local text logs
Section titled “Bound local text logs”[logging]max_size_mb = 250max_files = 10stderr = trueevent_retention_days = 90These are the existing defaults, not the older blueprint’s 50/5 sketch.
max_size_mb is a per-file MiB cap; max_files includes active mxr.log.
The defaults retain at most 2,500 MiB in named mxr text-log files. Zero values
and an overflowing aggregate cap are errors, not requests for unlimited logs.
The owned archive namespace is mxr. plus a 20-digit decimal sequence plus
.log, for example mxr.00000000000000000000.log. .mxr-log.lock serializes
writers across processes. A complete JSON record fits before rollover, including
one that lands exactly on the cap. Records larger than 64 KiB are replaced by
a small valid JSON warning, without copying the original content. Startup and
subsequent writes enforce reduced caps too: oversized existing owned files and
excess old archives can be discarded. An oversized active file at startup is
replaced with a bounded diagnostic. Unrelated names and symlinks are not rotated
or purged. Do not move the shared lock file while mxr writers are running.
Size/count/stderr settings are reread on writes; log level and RUST_LOG are
selected at process startup. Malformed TOML at startup uses tracing defaults so
config recovery commands remain available. If TOML becomes malformed while a
writer runs, it keeps its startup logging settings; config read I/O errors still
fail the write. Every record reopens the active path under the
shared lock, so a CLI rollover does not strand the daemon on an unlinked file.
When upgrading from append-only logging, run mxr restart after installing the
new binary so every writer uses this lock. Installation alone does not replace
an already-running older daemon; its old logger does not enforce these bounds.
An I/O failure can drop a record; it never recursively logs its own failure.
Where stderr is permitted, a fixed diagnostic reports that failure.
stderr = true mirrors the same bounded JSON records to stderr for ordinary
CLI commands and a foreground daemon. Tracing never writes stdout. Background
daemon launch, TUI/demo, stdio and dial-stdio paths stay file-only, even with
stderr enabled. stderr = false disables tracing mirroring, not command results
or explicit CLI error messages. Raw async-imap and tungstenite TRACE events
remain blocked before either sink. Log inspection and purge preview do not
initialize or rotate the logs they inspect.
Preview manual cleanup
Section titled “Preview manual cleanup”mxr logs --purge --dry-run --format jsonmxr logs --purge --format jsonPreview reports selected_log_files, event_cutoff, purged_log_files,
purged_event_rows and purged_sync_log_rows, with dry_run: true; the counts are what would be removed.
Apply uses the same archive selection and event timestamp predicate. Both use
event_retention_days (default 90). Time and data can change between invocations;
check a fresh preview before applying. This is not an immutable preview token.
Only old regular owned archives are selected. The active file, lock, unknown
names, symlinks and recent archives are preserved. Preview does not delete files,
create a missing database, migrate it or change event rows. Apply prunes old event_log
rows and old sync_log rows, keeping each account’s newest 50 sync rows. It does
not prune activity.
Purging event rows does not let a second unsubscribe go out: receipts for sent
unsubscribes live in their own table, which the purge never touches.
Filesystem and database cleanup are not a single transaction: an I/O error can
leave partial progress. The daemon also prunes event and sync history automatically once a day; see
automatic history retention. Activity’s existing
pruning is unchanged.
Inspect persisted events
Section titled “Inspect persisted events”The event log keeps mutation, sync, and rule events with structured columns. Filter by level, category, time, or free-text:
# Mutation events in the last daymxr history --category mutation --since 24h --format json
# Every sync error this week — search hits summary AND detailsmxr history --category-prefix sync --level error --search 'timeout' --since 7d
# Page through (offset + limit)mxr history --since 30d --limit 50 --offset 50What you get: an array of { timestamp, level, category, account_id?, message_id?, rule_id?, summary, details }. The --search flag searches both summary and details.
Live event stream
Section titled “Live event stream”Sometimes you want events as they happen — for example to wait on a sync that you just kicked off.
mxr events --type sync --format jsonlWhat you get: one JSON object per event. Pipe it into your status bar, a Slack webhook, or jq for filtering.
Activity: what you did
Section titled “Activity: what you did”Distinct from logs (system events) and events (mutation history), the activity log is a local record of every user-intent action across the TUI, CLI, and web. See the Activity Log guide for the full design — short version:
mxr activity list --since 24hmxr activity replay --since 1h # prose narrativemxr activity recall "yesterday afternoon"What you get: a reverse-chrono view of reads, archives, searches, sends. Strictly local — never transmitted off-device.
Surfaces
Section titled “Surfaces”All four lenses are reachable from one place:
- TUI (
G d): a six-pane Diagnostics screen —Status / Doctor,Data / Storage,Sync Health,Recent Events,Recent Logs,Activity Log.Tab/Shift-Tabto cycle,Enterto fullscreen one,Lto open the raw log file in$EDITOR. - Web (
/diagnostics): a tabbed Diagnostics page —Overview / Logs / Events / Activity. The Logs tab supports level filter, search, row-limit, and a pause toggle for the live tail. The Events tab supports level + category + free-text search + time window + paging. The Activity tab embeds the full activity browser with filters, bulk select, and pause controls. - CLI:
mxr status,mxr doctor,mxr logs,mxr history,mxr events,mxr activity ....
In real life
Section titled “In real life”- “Why did that batch archive fail?” —
mxr history --search 'archive' --level error --since 1h, then drill into thedetailsfield. If it’s a sync issue, follow up withmxr doctor --check --format json | jq '.sync_statuses'. - “What was the daemon doing during the last 10 minutes?” —
mxr logs --since 10m --limit 500 --format jsonl | jq -r '"\(.timestamp) \(.level) \(.message)"'. - “Did the prune actually run last night?” —
mxr activity list --action activity.pruned --since 24h. Synthesized markers show what the daemon did to its own data. - “I keep seeing intermittent failures. Make me a bug report.” —
mxr bug-report --githubopens a pre-filled issue with status, recent events, log tail, and config (sanitized).
Notifications and quick counts
Section titled “Notifications and quick counts”mxr notify # unread counts for the status barmxr notify --format json --watch # JSON stream for tmux, polybar, sketchybarmxr count "label:inbox is:unread"Agent prompts that work
Section titled “Agent prompts that work”"Run `mxr doctor --check --format json` and `mxr history --since 24h--level error --format json`. Summarise findings under three headings —**Critical**, **Yellow**, **Green** — and propose at most one concretenext command for each. Don't run mutating commands.""Use `mxr logs --since 10m --format jsonl` plus `mxr activity list--since 10m --format json` to reconstruct what happened in the last tenminutes. Tell me first what *I* did, then what the *daemon* did, thenflag anything unexpected."Bug reports
Section titled “Bug reports”When you need a shareable diagnostic bundle:
mxr bug-report # writes a Markdown filemxr bug-report --stdout # prints to stdoutmxr bug-report --github # opens a pre-filled GitHub issuemxr bug-report --full-logs # include every log line from today (still sanitized)Or open the TUI Diagnostics screen and press b for one-click bug-report.
See also
Section titled “See also”- Activity Log — the user-intent record (separate from system events).
- Security & Privacy — what stays local in mxr.
mxr logs,mxr history,mxr events,mxr activity— CLI references.[logging]and[activity]config keys.