Quick Diagnosis
Use this order when something feels broken:
- Check permission status in Settings -> Permissions.
- Run Engine Test Setup.
- Dictate in both an editor and a terminal.
- Inspect History insertion status for latest entries.
This usually isolates whether the issue is recording, transcription, cleanup, or insertion.
Common Issues
| Symptom | Likely cause | Fix |
|---|---|---|
| Option key does nothing | Input Monitoring denied or monitor not re-registered | Grant permission, refresh permissions, relaunch Steno |
| Hands-free key fails | Global toggle disabled or conflicting key | Set F13-F20 key in Recording settings |
| "File not found" in Engine section | Wrong whisper-cli or model path | Update paths and rerun Test Setup |
| Transcription works but no text appears | Accessibility denied or method ordering mismatch | Grant Accessibility and test insertion order |
| Terminal output is inconsistent | Direct typing unsuitable for target terminal | Keep clipboard fallback and prioritize terminal-safe behavior |
| Cloud cleanup not running | Missing API key or budget guard disabled cloud mode | Save API key and verify cleanup mode |
| Onboarding blocked on permissions | Microphone not granted | Grant microphone in System Settings and retry |
Advanced Debugging
If the basic matrix does not resolve the issue:
- verify
whisper-cli --helpruns from your configured path - rebuild
vendor/whisper.cppfrom pinned version - re-generate project with
xcodegen generate - confirm app signing identity did not change unexpectedly
- check whether failures are app-specific (bundle ID context)
For insertion-only issues, compare outcomes:
- editor test
- terminal test
- browser text field test
This helps isolate app compatibility vs global configuration issues.
Before Reporting
When opening an issue, include:
- macOS version
- Steno commit/tag or branch
- exact failing step
- whether failure is global or app-specific
- current permission states
- configured insertion method order
- screenshot or text of Engine Test Setup result
This context dramatically reduces triage time.