Voice coding on a Mac: a practical setup
Voice coding now means two different jobs. Dictating intent to an AI agent needs only a good dictation app: hold a key, describe the change, and the agent writes the code. Speaking code and commands hands-free needs a command system such as Talon with Cursorless, or macOS Voice Control. Most developers want the first; some need the second.
Two kinds of voice coding
Until recently, coding by voice meant saying every token: a spoken grammar for symbols, selections and edits, learned like a second keyboard. That still exists and is still the answer for anyone who cannot use their hands. What changed is that most code is now written by describing it. If an agent in Claude Code or Cursor does the typing, the part left for you is prose, and prose is what dictation is good at.
| Dictating intent | Speaking code and commands | |
|---|---|---|
| What you say | “Add retry with backoff to the upload client and cover it with a test” | “select all”, “delete word”, “undo that”, plus a grammar for symbols |
| Who writes the code | The agent | You, by voice |
| What you need | A system-wide dictation app, or Claude Code's /voice | Talon (often with Cursorless) or macOS Voice Control |
| Time to get going | Minutes | A command vocabulary to learn first |
| Best for | Anyone working with Claude Code, Cursor or a chat panel | Hands-free work: an injury, a disability, or keeping one from getting worse |
Dictating to an agent: the setup that works
- Pick a dictation app that works in every windowThe agent's prompt is one of five places you type: there is also the shell, the commit box, the pull request and the chat with your team. An on-device app matters here, because prompts name unreleased features, customers and security holes. FreeFlow listens for ⌥ anywhere and transcribes on the Mac; the comparison guide lists the alternatives.
- Make a Code modeIn FreeFlow, Modes → +. Parakeet V2 if you only speak English (6.1% average word error rate, the fastest), Parakeet V3 otherwise. Leave formatting off, so an identifier is never “corrected” into an ordinary word.
- Put your identifiers in the dictionarySpeech models are trained on prose, so
useEffectarrives as “use effect” andkubectlas something worse. On the Dictionary page, add each one as a replacement: what was heard, then the spelling you want. Replacements rewrite exactly, on every model. Ten minutes with your framework names, services and teammates' names pays for itself the same day. - Dictate everywhere you typeHold ⌥ in the agent's prompt, in the terminal (text lands without a newline, so nothing runs until you press Enter), in the Source Control box, and in the browser for the pull request description.
- Let the agent's questions come to youWith Claude Code connected, FreeFlow shows a small card when a session stops for a plan approval, a question or a permission. Plans and questions can be answered by voice from whatever window you are in. Permission cards are click-only on purpose.
What to say: prompts that survive being spoken
- Goal, then constraints, then the check. “Make the export resumable. Do not change the public API. I will know it works when the interrupted-download test passes.” Spoken prompts wander; this order keeps them usable.
- Name things the way your dictionary spells them. Say the file and the symbol. The replacement does the spelling.
- Describe structure, do not recite it. “A function that takes a list of users and returns the active ones” beats dictating brackets and arrows.
- Use ⌥Space for anything long. It toggles hands-free recording, so you can think out loud for a minute without holding a key.
- Read before you press Enter. A wrong word in a prompt is cheap to fix before it is sent and expensive after.
Speaking code itself: Talon, Cursorless and Voice Control
If you need to work without a keyboard, a dictation app is not enough, FreeFlow included. It types what you say; it does not select a line, click a button or move the cursor. Three tools do.
- [Talon](https://talonvoice.com/) describes itself as hands-free input. It combines voice commands and dictation with eye tracking for the pointer and mouth noises for clicking and scrolling, and you define your own commands in small script files. It is a free download for macOS, Windows and Linux (X11).
- [Cursorless](https://github.com/cursorless-dev/cursorless) calls itself “a spoken language for structural code editing”. It puts a marker on every token on screen so you can name a target and an action in a few syllables. It currently depends on Talon.
- [macOS Voice Control](https://support.apple.com/guide/mac-help/mh40719/mac) is built into System Settings → Accessibility. You speak commands to open apps, click, scroll, and dictate and edit text, with separate Dictation, Spelling and Command modes. Apple's guide also describes a Swift mode that writes Swift code as you read it aloud. While Voice Control is on, standard macOS Dictation is unavailable.
These are not rivals to a dictation app so much as a different layer. A common arrangement is a command system for navigation and editing, and a dictation app for the long passages: prompts, comments, commit messages, messages to people.
| Tool | What it does | Cost |
|---|---|---|
| FreeFlow Dictation | Dictation into any app, on-device; answers Claude Code's plan and question cards by voice | $99 once, 14-day trial |
Claude Code /voice | Dictation into the Claude Code prompt only; audio goes to Anthropic | No extra charge; needs a Claude.ai sign-in |
| Talon | Voice commands, dictation, eye and noise input, scripting | Free download; a paid tier adds features and support |
| Cursorless | Structural code editing by voice, on top of Talon | Open source |
| macOS Voice Control | Commands for the whole Mac, plus dictation and text editing | Included with macOS |
Where voice is still the wrong tool
Dense symbol work, such as a regular expression or a long type signature, is faster typed unless a command grammar is already second nature. An open office makes any microphone self-conscious, though a headset with a boom mic and a quiet voice goes further than people expect. And a spoken prompt is a first draft: the time saved speaking it is real only if you still read it before it runs.
Questions people ask
Can I code entirely by voice on a Mac?
Yes, with a command system: Talon with Cursorless, or macOS Voice Control. A dictation app alone covers prompts, comments and commit messages, not hands-free editing and navigation.
Do I need Talon to use Claude Code by voice?
No. Dictating prompts needs only a dictation app or Claude Code's own /voice. FreeFlow adds one more thing: answering Claude's plan and question cards out loud.
Why does dictation get my function names wrong?
Speech models learn from ordinary prose, so an identifier is heard as the nearest words. Add it as a replacement in the dictionary and it is spelled your way from then on.
Is on-device dictation accurate enough for technical prompts?
For prose, yes: Parakeet V3 averages a 6.3% word error rate on the Open ASR Leaderboard. Identifiers are the weak spot, and the dictionary is the fix. An agent also tolerates a slightly wrong word better than a compiler does.
Does voice coding help with RSI?
Many people take it up for that reason, and less typing is less load on the hands. The accessibility page covers what FreeFlow can and cannot do there. It is not medical advice.