Yappy troubleshooting
Almost every Yappy problem is a macOS permission problem wearing a disguise.
The hotkey does nothing
Cause: Accessibility is not granted, or was granted after launch.
macOS reads the Accessibility grant when the app starts and does not re-read it live. So the sequence that works is: enable it, then quit and relaunch Yappy.
System Settings → Privacy & Security → Accessibility → Yappy → on, then quit Yappy from the menubar and open it again.
If Yappy is already listed and enabled but the key still does nothing, remove the entry with the minus button, relaunch, and let it re-add itself. macOS keeps the grant keyed to the app's signature, and a rebuilt or re-downloaded copy is a different signature to it.
Dictation records but nothing is typed
The transcription worked and the insertion did not. Two usual causes:
- No editable field is focused. Click into the text field first.
- The target app blocks synthetic paste. Some secure fields do, by design. Password fields will never accept dictated text.
It hears silence
Check System Settings → Privacy & Security → Microphone → Yappy. If the permission is on and Yappy still hears nothing, check the input device in Sound — a disconnected headset that macOS still lists as the input is the common culprit.
Dictation in a noisy room is a different problem: voice isolation is on by default, and upgrading to large-v3-turbo helps more than anything else. See dictation.
The lid is closed / clamshell mode
With the lid shut and an external display attached, the built-in microphone is unavailable. Yappy warns rather than silently recording nothing. Use an external mic or open the lid.
Agent Mode does not start
Agent Mode needs the claude CLI, separately from your cleanup backend:
which claude || curl -fsSL https://claude.ai/install.sh | bash
claude # sign in, then /exitIf claude is installed somewhere other than /opt/homebrew/bin/claude, Yappy corrects claudeBin at launch — but a relaunch is what triggers that.
Dictation is slow
The cleanup backend is almost always the reason. claudeCode is 4–6 seconds by nature; ollama is 1–3; the hosted plan is under one. See backends. Turning AI Cleanup off removes the step entirely and pastes the raw transcript instantly.
Text arrives with a stray dash
Fixed in the transcript filter — subtitle-style dialogue in the training data made Whisper start lines with a dash. Update to the current version. If you see it mid-sentence rather than leading, mail [email protected] with the sentence; that variant is still being tracked.
Updates are not arriving
autoUpdate is on by default and checks a signed appcast, verifying the publisher's Apple team ID before installing. If your network blocks the R2 endpoint, download the current .dmg from yappy.biz/download and drag it over the old copy — settings and models are kept.
Still stuck
Menubar → Send Feedback attaches the app version, macOS version, and the recent log tail, which turns a two-day exchange into one message. Or write to [email protected] directly.