Skip to content

Troubleshooting

Jump to bottom
Chris Schroedinger edited this page Jul 3, 2026 · 2 revisions

Troubleshooting

Start here: agentwhisper status — every subsystem reports its health there, and most error messages contain their own fix. The full log is at ~/.local/state/agentwhisper/daemon.log.

Reading agentwhisper status

Line Healthy value If not
engine: ready loading = model still downloading (first run — wait). error: … = the message says what failed
hotkey: f12 — grabbed (exclusive) See "hotkey unavailable" below
desktop: ok Names the missing tool and the apt command
tray: active See "no tray icon" below
visualizer: active Install python3-gi-cairo, restart

No tray icon

sudo apt install python3-gi python3-gi-cairo gir1.2-ayatanaappindicator3-0.1
cd agentwhisper && ./install.sh    # rebuilds the environment if needed

The app still works without the tray (control it with the agentwhisper command) — but on XFCE the icon should always appear.

"could not reserve 'f12'"

Another program holds a grab on exactly that key. With AgentWhisper not running, press F12 and see what reacts (drop-down terminals like Guake or Tilda are the usual suspects) — unbind it there, or give AgentWhisper a different key in the config (key = "scroll_lock").

Dictated, but no text appeared

  1. agentwhisper status → engine: must be ready (loading = model still downloading, first run only)
  2. desktop: must be ok — otherwise install the named tool
  3. Taps under ~0.3 s are ignored on purpose; silence transcribes to nothing ("No speech detected" notification)
  4. If typing failed, the text is still in your clipboard — Ctrl+V

"No speech detected" though you spoke

Test the microphone: arecord -d 3 test.wav && aplay test.wav. If you hear nothing, pick the right input device in your sound settings (AgentWhisper uses the system default input).

GPU (device = cuda) errors about cuDNN

CUDA mode needs cuDNN 9 for CUDA 12 installed. If in doubt, stay on the CPU defaults (device = cpu, compute_type = int8) — they are fast enough for the default model.

Still stuck?

Attach the last lines of ~/.local/state/agentwhisper/daemon.log to a GitHub issue — every failure is logged with its stage and reason.

AgentWhisper

Repository · Changelog

Clone this wiki locally