Overview
tmux-whspr is a local-first voice dictation tool built for terminal workflows on macOS. It records audio via ffmpeg, transcribes on-device with whisper.cpp, and pastes the result directly into your active tmux pane. Everything stays on your machine — no cloud, no subscriptions, no round-trip latency. Optional LLM post-processing via Cerebras API is available for cleanup and reformatting when you want it.
It is designed around a single constraint: dictation should never interrupt what you are doing.
How it works
In background mode, tmux-whspr spawns a recording process in a separate pane. You keep working. When you stop recording, transcription runs asynchronously — whisper-cli processes the audio and the text is injected into your session via tmux’s send-keys. No waiting, no modal overlays, no focus shifts.
Inline mode is available when you want immediate dictation in the foreground — press to record, release to transcribe, and the result is pasted on the spot.
Mode awareness lets you tailor output to context. Code mode applies prompts that favor identifiers and syntax over prose. Long mode is tuned for extended dictation. Custom modes let you define your own prompt context per project or workflow.
Vocabulary management is a first-class feature. You can import term lists, deduplicate entries, and export the vocabulary as a whisper prompt file — critical for getting domain-specific names, acronyms, and jargon transcribed correctly.
Audio device management handles the noise of real-world setups. tmux-whspr auto-detects connected microphones — external USB mics, iPhone as mic via Continuity Camera, or the built-in input — and lets you switch between them without hunting through system preferences.
SwiftBar and Raycast integrations expose recording controls outside the terminal for when you need them.
Distribution is via a Homebrew tap, so setup is one command.
Status
Active development at v0.5.0-17. The core workflow is stable and in daily use. Ongoing work includes expanded mode definitions, improved vocabulary tooling, and additional integrations.