Diagnostics and getting help¶
When something is not working, Amri has two tools to find out why: a self-check you run on demand, and a local flight recorder that captures a problem as it happens. Both are on your machine, and nothing leaves it unless you choose to send it.
amri doctor¶
amri doctor runs a quick check-up and prints plain-language findings. Run
it whenever Amri is not behaving:
It runs an input check on the spot: Amri sends a test keypress through the virtual input device and reports whether it arrived. It also surfaces the most recent diagnosis recorded by the debug bag (below), so a recognition problem captured during a real session is reported here in plain language. If nothing has been recorded yet, it says so.
The findings read as questions you can act on, such as "Is your mic muted?", rather than raw numbers.
If the input check fails, the permission step in Setup is the usual cause.
The debug bag¶
The debug bag is a local flight recorder. It holds a rolling window of recent
audio and recognition results in memory, and packages that window into a single
.amribag file only when an error occurs. This is what lets a problem that
happened seconds ago be examined after the fact, with no setup on your part.
It is on by default in on_error mode, which keeps the window in memory and
writes a bag only when a triggering error is logged.
Recording a bag does not change how Amri behaves. The audio copy runs off the recognition path, so a running Amri sounds and responds the same whether the recorder is on or off.
Local-only¶
Bags are written under your local state directory and are never uploaded. A bag leaves your machine only if you export one yourself, for example to attach it to a support report. A bag holds the recent audio plus device and environment detail, so it stays under your control by default.
Configuring it¶
The debug bag is configured only in engine.toml, never in a profile. This is so
an imported profile cannot switch on a recording of your own machine. The shipped
default is:
[debug_bag]
enabled = true
mode = "on_error" # off | on_error | continuous | manual
# window_seconds = 30 # pre-error rolling window held for the bag
# max_megabytes = 64 # hard cap on the in-memory window + bag size
To turn the recorder off entirely, set enabled = false.
| Key | Effect |
|---|---|
enabled |
true keeps the recorder running; false removes it entirely |
mode |
off, on_error (write on an error), continuous, or manual (write on request) |
window_seconds |
Seconds of audio kept in memory for the bag |
max_megabytes |
Hard cap on the in-memory window and the bag size |
Consent lives with you
The recorder is configured only in engine.toml, a file you control. A shared
or imported profile cannot enable it. Removing the [debug_bag] section is
treated as off, and a deliberate enabled = false is left untouched.
Log level¶
When you or support needs more detail about a run, raise the log verbosity. Set
log_level in engine.toml to change it for every run:
The default is info. Lower levels such as debug and trace print more; warn
and error print less.
To raise it for a single run without editing the file, pass --log-level:
The command-line value overrides engine.toml for that run only.
Machine-readable output
amri --log-format json renders each recognition result as one line of JSON,
which is the form a support tool reads. The default, text, is meant for a
person.