Voice dictation for Claude Code
FreeFlow Dictation gives Claude Code two things its built-in /voice does not: on-device dictation into any surface — the prompt, the shell, Cursor, a browser — and a card that lets you answer Claude Code's plan approvals, questions and permission prompts out loud without leaving the window you were working in. No audio leaves the Mac.
What Claude Code already gives you
Claude Code ships voice dictation of its own. Run /voice in the CLI (v2.1.69 or later), hold Space, speak, release, and the transcript lands in the prompt box; a tap mode starts and sends with single presses. It is tuned for coding vocabulary — regex, OAuth, localhost — and quietly adds your project and branch names as recognition hints. It does not count against your usage limits. Those are real strengths, and if the prompt box is the only place you type, you may need nothing else.
Three facts from Anthropic's own documentation shape everything that follows. Audio is streamed to Anthropic's servers; it is not processed locally. It needs a Claude.ai sign-in — it is unavailable with an API key, Bedrock, Vertex or Foundry. And it needs a local microphone, so it does not work in SSH or cloud sessions.
Where /voice stops
- It only fills the prompt. Everything else you type during an agentic session — the shell command you run to check its work, the commit message, the reply in Slack, the prompt to a second tool — is outside its reach.
- It does not answer Claude's questions. When Claude Code stops to ask which approach you prefer, to show you a plan for approval, or to ask permission to run a command,
/voiceis not involved. You switch to the terminal and click or type. - It is one language at a time, from a list of 20, set in
/config. - Your voice goes to a server, which is fine for most code and not fine for every client's code.
What FreeFlow adds
Dictation anywhere, on your Mac. Hold ⌥ in any text field — Claude Code's prompt, iTerm, Cursor's chat, Xcode, a browser — and the words land at the cursor. Transcription runs on the Neural Engine through Parakeet V3 (6.3% average word error rate on the Open ASR Leaderboard) or any of five other models. Teach the dictionary your identifiers once and useEffect, kubectl and your repo's odd names come out spelled right from then on. A mode can strip fillers and tidy a long prompt with Apple Intelligence before it is pasted, with nothing sent anywhere.
Cards for the moments Claude needs you. Connect FreeFlow in Settings → Claude Code and a small card appears whenever a session stops for you: a question with options, a plan to approve, a command to allow, or a finished turn. Click an answer, or hold ⌥ and say it — “use CPU and GPU” finds the option called “CPU & GPU”, and anything else goes through as a free-form reply. The card is built so it cannot take keyboard focus, so your cursor never moves out of what you were doing. It names the project and branch that is asking and steps through sessions when more than one is waiting.
| Claude Code /voice | System-wide dictation | FreeFlow Dictation | |
|---|---|---|---|
| Works in | The prompt box only | Any text field | Any text field, plus Claude's own cards |
| Audio is processed | On Anthropic's servers | Depends on the app | On your Mac |
| Account | Claude.ai sign-in required | Varies | None |
| Answer a plan, question or permission by voice | No — click or type in the terminal | No | Yes (permissions stay click-only) |
| Languages | 20, one at a time | Varies | 25 on Parakeet V3, 99 on Whisper, per mode |
| Over SSH / in cloud sessions | No | Dictation yes; nothing else | Dictation yes; cards only for sessions running on this Mac |
| Costs | Included with a Claude.ai plan | Varies | $99 once, three Macs |
- Install FreeFlow and allow its two permissionsDownload it, drag it to Applications, and grant Microphone and Accessibility when asked. The 14-day trial is the full app.
- Open Settings → Claude Code and click ConnectFreeFlow adds tagged hook entries to
~/.claude/settings.jsonand keeps a copy of the original beside it assettings.json.bak-freeflow. Disconnect removes exactly those entries again. - Choose which cards you wantPlans and questions, permissions, and finished turns each have their own switch. Most people start with all three.
- Start a Claude Code session and wait to be askedThe card appears over whatever you are doing. Click an option, or hold ⌥ and say it. Ignore it for 45 seconds, or press Esc, and the prompt goes back to Claude's own window as if FreeFlow were not there.
Or install it as a Claude Code plugin
The same five hooks are also published as a Claude Code plugin, for people who would rather not have an app edit ~/.claude/settings.json. One line in your shell:
claude plugin install freeflow-dictation --marketplace freeflow-dictation/freeflow-dictation-pluginsOr in two steps: claude plugin marketplace add freeflow-dictation/freeflow-dictation-plugins, then claude plugin install freeflow-dictation@freeflow-dictation. FreeFlow 1.7.4 or later notices the plugin by itself — Settings → Claude Code reads “Connected through the Claude Code plugin” and Connect steps aside, so the hooks are never registered twice. The plugin is MIT-licensed and open: the plugin and its marketplace are on GitHub, and the plugin itself is a thin set of hook registrations; the program that does the work ships inside the app.
How the bridge works
Claude Code runs a small helper, freeflow-agent-hook, as a hook on four events: PreToolUse for ExitPlanMode and AskUserQuestion, PermissionRequest, and Stop, with two housekeeping events so a card never outlives the session that raised it. The helper writes Claude's JSON payload to ~/Library/Application Support/FreeFlow/agent/, FreeFlow shows the card, and your answer is written back and printed to Claude. No network, no port, no daemon.
The helper is built never to be load-bearing. It exits 0 in every case — a non-zero exit would be a blocking error in Claude Code — and prints nothing whenever FreeFlow is not running, not connected, or does not answer in time, which makes Claude prompt you in its own window exactly as it would have anyway. If FreeFlow quits while a card is up, the session carries on within a second. The full detail is in the hook documentation.
Use both
The two do not fight. /voice listens for Space inside Claude Code's prompt; FreeFlow listens for ⌥ everywhere. Plenty of people keep /voice on for quick prompts and reach for ⌥ when the prompt is long, when they are in the shell or Cursor, or when a card appears. If your Claude Code runs through an API key or Bedrock, where /voice is unavailable, FreeFlow is the only voice option that works.
Questions people ask
Does this work with the Claude Code VS Code extension?
Dictation does: the extension's chat box is a text field like any other, so hold ⌥ and speak. The cards come through hooks in your user-level ~/.claude/settings.json, which the extension reads as well, so sessions started there raise cards too.
Do I need /voice turned on?
No. The two are independent. FreeFlow does not use Claude Code's speech service and /voice does not use FreeFlow's models.
Plugin or Connect — which should I use?
Either, not both. Connect in Settings writes the hooks into your settings.json and keeps a backup; the plugin registers the same hooks through Claude Code's plugin system and leaves that file's hooks alone. Pick the plugin if other tools share your settings.json, or if you manage plugins already.
Can a misheard word approve a command?
No. Permission cards accept clicks only; voice is deliberately disabled on them. Questions and plans take voice because the worst case there is an answer you can correct.
What happens if FreeFlow is not running?
The hook sees no live FreeFlow and yields instantly. Claude Code prompts you in its own window exactly as it does without FreeFlow.
Does it work over SSH or in Claude Code on the web?
Dictation into the terminal works anywhere the terminal is local to your Mac. The cards do not: the hook runs on the machine where Claude Code runs, and a remote host cannot see the FreeFlow on your laptop.
Does answering by voice use my Claude tokens?
No. Nothing FreeFlow does touches the Claude API. Your spoken answer becomes the same text you would have typed.