Who Voice Assistant is for#
Developers running hands-free coding sessions
You describe a task out loud, Assistant routes it to Claude Code in your project's folder, and you hear the answer as it finishes. The persistent session means follow-ups stay in context without re-stating what you are working on. You can walk away from the desk during a long task and hear the result when it completes.
Skip if:
Skip if you work primarily at the keyboard. The setup requires sox, whisper-cpp, ffmpeg, and a Whisper model download, and only pays off if voice is a regular part of your development workflow rather than an occasional convenience.
Developers checking Claude Code status by voice
After Claude Code finishes a task, you can ask for the status of a deploy, hear file names mentioned, or follow up on what was changed, all without looking at a terminal. Short conversational queries and status checks work well; longer context-heavy questions benefit from the panel at localhost:4780.
Skip if:
Skip if your Claude Code answers are typically multi-file diffs or dense code blocks. Hearing a 200-line diff read aloud is rarely useful; this fits best for conversational status checks and short explanations.
Developers who want voice-confirmed deployments
Push, deploy, publish, and messaging actions wait for a spoken yes before executing. You can say the wake word, describe what you want, hear what Claude Code plans to do, and confirm out loud. The confirmation list is configurable from the app's settings and updates immediately.
Skip if:
Skip if you are not yet using Claude Code for deployment tasks. The confirmation gate is only meaningful if Claude Code is already part of your deploy or release workflow.
Solo developers running an ambient coding assistant
Voice Assistant keeps one Claude Code session open all day in your working directory. A short journal bridges sessions across days so context is not lost on a restart. You can speak a question from anywhere in the room, hear the answer, and return to the keyboard only when you need to review code.
Skip if:
Skip if you share a machine or work in an open office. The always-listening microphone and spoken answers do not suit shared environments or spaces where you cannot speak freely.
The problem it solves#
Talking to Claude Code while away from the keyboard means switching between a microphone input and a screen. Voice dictation tools let you speak a prompt into the terminal or a chat interface, but as soon as Claude replies, you have to walk back, read the screen, and dictate the follow-up. For developers running longer tasks from another room, reviewing a build result while away from the desk, or trying to keep their hands free, that read-and-dictate cycle breaks the hands-free idea.
The deeper friction is the response side. Claude Code often returns multi-sentence answers with file names, diffs, or status updates. Reading those back yourself defeats the purpose of voice input. Most existing voice tools, paid or free, stop at transcription; they turn your speech into text and get out of the way. Nothing in that loop speaks the answer back to you.
How it solves it#
Local Whisper transcription
Audio stays on your Mac. Whisper runs locally using models you download once, from tiny to large-v3-turbo. The engine cuts utterances by energy level with an adaptive noise floor and drops hallucinations Whisper produces on silence, so stray background noise does not trigger requests. Only the transcribed text leaves the device.
Persistent Claude Code session
One Claude Code session runs all day in a folder you choose. After a restart, the same session resumes. When a conversation ends, a one-shot Claude Code writes a short summary into a local journal that the next session reads, so context carries across days without growing unbounded.
Sentence-by-sentence streaming answers
Answers are spoken as they arrive, sentence by sentence, rather than waiting for the full response. With a Fish Audio key and voice id, each sentence is synthesized ahead of the one playing; without one, the Mac's built-in say command speaks it. Say the wake word mid-speech and Assistant stops immediately to listen.
Wake word with speaker disambiguation
Without the wake word, a small on-device model reads the utterance and the last few exchanges to decide whether the request was directed at Assistant (based on Mallidi et al., Device-directed Utterance Detection, 2018). If not, the phrase goes to a draft. A reply within 60 seconds of the last answer does not need the wake word again.
Confirmation gate for risky actions
Six action types wait for a spoken yes before executing: push, deploy, publish, messaging someone, deleting, and paying. Reading, searching, and editing local files proceed without a prompt. The confirmation list is configurable from the app's Settings screen and takes effect immediately.
Web panel for session visibility
A panel at localhost:4780 shows everything Assistant heard, everything it ignored and why, the tools it ran, and the cost of each answer in Claude tokens. You can type requests there instead of speaking, which is useful when a microphone is not available or when reviewing what happened across a session.
Strengths and trade-offs#
Strengths
- Audio never leaves your MacWhisper runs on-device. The only data that leaves is the transcribed text of your requests, which goes to Anthropic through your own Claude Code subscription, the same data path you use when typing. If you configure Fish Audio for a custom voice, the text of each spoken sentence goes to Fish Audio; without it, nothing leaves except the Claude Code requests.
- MIT licensed with no subscription requiredThe app is MIT licensed and requires no Voice Assistant account or monthly fee. You need Claude Code signed in and three Homebrew dependencies. Unlike paid dictation tools, there are no tiers, seat limits, or per-voice charges tied to the voice layer itself.
- Completes the full voice agent loopMost voice tools stop at transcription; your speech becomes text, and you read the response yourself. Voice Assistant handles the response side too; it routes spoken requests to Claude Code and speaks the answers back. For hands-free development, this is the key differentiator versus Superwhisper and similar paid apps.
- Signed and notarized by AppleThe .dmg is signed with the developer's Developer ID and notarized by Apple. It opens from Safari or Finder without a Gatekeeper warning, which matters for a menu bar app installed from a direct download link rather than the Mac App Store.
Trade-offs
- -Apple Silicon and macOS 14 or newer requiredThe app does not run on Intel Macs or macOS 13 and older. The echo cancellation that removes Assistant's own voice from the microphone depends on macOS hardware and OS version. There is no compatibility mode or fallback for older hardware.
- -Silent during long-running tasksDuring a task that takes more than a few seconds, Assistant announces what it will do and then goes quiet until the task ends. It does not narrate progress or intermediate steps. For multi-minute agent tasks, you will not hear status updates until the final answer arrives.
- -Does not start at loginYou must launch Assistant manually after each restart. There is no built-in login item option. It is not available until you open it from /Applications or the Dock.
- -English and Brazilian Portuguese onlyThe interface, wake words, spoken phrases, and prompts sent to Claude follow the Mac's system language. You can fix the language to English or Brazilian Portuguese in the config file, but no other languages are supported.
Voice Assistant vs alternatives#
Voice Assistant vs Superwhisper
Both tools run on macOS Apple Silicon and use local Whisper for speech transcription. The difference is in scope. Superwhisper is a general-purpose dictation tool that converts speech to text and pastes it in any app; Voice Assistant is a specialized voice interface for Claude Code that handles both input and output.
| Feature | Voice Assistant | Superwhisper |
|---|---|---|
| License | MIT | Proprietary |
| Price | Free | Paid subscription |
| Transcription | Local Whisper (on-device) | Local Whisper (on-device) |
| Response | Spoken aloud by the app | None (text only) |
| Integration | Claude Code only | Any app (universal dictation) |
| Self-hosting | Native Mac app, no server | Managed app, no server |
| Audio leaves Mac | No | No |
Voice Assistant is the better choice when your goal is to operate Claude Code by voice end-to-end. You speak a request, it routes to Claude Code, and the answer comes back as speech. You can follow a long-running agent task without sitting at the screen. The confirmation gate for risky actions (push, deploy, delete) adds a safety layer that dictation alone does not provide.
Superwhisper is the better choice when you want voice input across your entire Mac, for composing emails, filling forms, dictating messages in Slack or Linear, or adding text anywhere your cursor sits. It is not tied to any one app. If your use case extends beyond Claude Code, Superwhisper covers more ground, and its polish and feature set reflect several more years of development.
Quick start#
Run the setup script to install on macOS 14+ Apple Silicon.
```bash
curl -fsSL https://blob.ciromaciel.click/tools/voice-assistant/install.sh | bash
```What it's built on#
- Languages
- JavaScriptSwiftTypeScript
- Runtimes
- Bun
FAQ#
What do I need to install before running Voice Assistant?
You need Claude Code with an active login, three Homebrew packages (sox, whisper-cpp, and ffmpeg), and a Whisper model downloaded via the script in the repository. The app installs with one curl command or a .dmg download. On first launch, macOS will ask for microphone permission.
Does Voice Assistant send my audio to any server?
No. Your voice is transcribed by a local Whisper model on your Mac and never sent anywhere. Only the transcribed text of your requests goes to Anthropic, through your own Claude Code subscription, the same path as when you type. If you configure a Fish Audio voice, the text of each spoken sentence goes to Fish Audio; without it, nothing leaves except the Claude Code requests.
How does Voice Assistant differ from Superwhisper?
Superwhisper is a general-purpose voice dictation app; speech becomes text that lands at your cursor in any app. Voice Assistant is specific to Claude Code; it routes your spoken request to an active coding session and speaks the response back aloud. The two tools solve different problems, and Superwhisper does not handle the Claude Code response loop.
Which Claude model does Voice Assistant use by default?
The conversation model defaults to claude-haiku-5-5. You can change it to any Claude model by editing ~/.config/voice-assistant/config.json (the brainModel key) or by setting the ASSISTANT_MODEL environment variable. The app's Settings screen also surfaces microphone, Whisper, voice, and folder settings, all of which take effect immediately.
Can I use a custom voice instead of the Mac's built-in speech?
Yes. With a Fish Audio account and API key, you can configure any voice from the Fish Audio library. Set fishApiKeyFile to a dotenv file containing your FISH_API_KEY and fishVoiceId to the voice you want. Each sentence is synthesized one ahead of the one currently playing, so the response flows without gaps. Without a Fish Audio key, Assistant uses the Mac's say command with a configurable voice name, defaulting to Samantha in English.
Similar open-source tools#
Speech To Text
2 GitHub starsLocal speech-to-text that types where your cursor is
Alternative to
Wispr Flow
Diction
239 GitHub starsiOS keyboard with self-hosted speech-to-text, no word limits
Alternative toWispr Flow
FU Flow
2 GitHub starsFree offline voice typing for Windows 10/11 and Ubuntu Linux
Alternative toWispr Flow
Voquill
1,019 GitHub starsOpen source voice dictation with local AI and custom glossary
Alternative toWispr Flow
VoiceInk
6,840 GitHub starsPrivate voice dictation for Mac, no subscription required.
Alternative to
Superwhisper
FreeFlow
2,931 GitHub starsFree, open source Mac dictation with AI cleanup and voice macros
Alternative toWispr Flow