Voice Prompting the Pi Coding Agent on Mac
By Kiran Jd
Published
To dictate into Pi on Mac, start pi in your project folder, keep the terminal window in front with the cursor in Pi's editor at the bottom, and dictate with your Speakmac shortcut. Read the text before pressing Enter, because Enter sends. If a transcript does not land, copy it from Speakmac and paste it into the editor.
Pi is a minimal, open-source coding agent that runs in your terminal. Mario Zechner started it as pi-coding-agent, and it is now maintained by Earendil, which shipped Pi 1.0 on 1 October 2026. It is not Inflection's Pi chat assistant, and it has nothing to do with Raspberry Pi. Speakmac supplies the words; the model you select in Pi does the work after you send.
Where does the prompt go in Pi?
Pi's interactive screen has the conversation at the top, an editor below it, and a footer showing the working folder, model and context use. You type in the editor. Run Pi from the folder you want it to work in, because that folder decides which files it reads and which AGENTS.md instructions it loads.
The editor keys matter more for voice than for typing (Pi usage docs, keybindings):
| Key | What it does in Pi |
|---|---|
Enter | Sends the prompt. While Pi is working, it queues a steering message instead |
Shift+Enter or Ctrl+J | New line without sending |
Alt+Enter | Queues a follow-up for after the current task |
Ctrl+G | Opens the prompt in your external editor |
Escape | Stops the current task |
@ | Fuzzy-searches project files to attach |
How do you dictate a task into Pi?
- Install Speakmac and finish microphone and Accessibility setup. Choose a dictation model that suits your Mac.
- Open your terminal,
cdinto the project and runpi. Sign in or set up a provider with/loginfirst if you have not already. - Click inside the terminal window so Pi's editor has focus. Close any selector or overlay such as
/modelor/treefirst, or the text goes into its search box instead. - Hold your Speakmac Push to Talk shortcut, or use Hands-Free, and describe the change, the current behaviour, the constraints and how you will know it worked.
- Fix identifiers, add
@file references by typing, then press Enter.
Leave Speakmac's Send After Dictation shortcut unused while you are learning this. It presses Return after inserting the text, and in Pi that sends at once, or steers a task that is already running.
What is a useful voice prompt?
Pi keeps its system prompt short and has no plan mode, so the brief you send carries a lot of weight. Say the outcome and the check:
The import command crashes on an empty CSV. Make it print "nothing to import" and exit cleanly. Do not change the output for normal files. Add a test for the empty file and run the existing import tests.
For larger work, ask for a plan in a file first, which is the approach Pi's own README suggests in place of a plan mode:
Before editing anything, read the billing module and write a short plan to PLAN.md: which files change, in what order, and what could break. Stop after writing the plan so I can review it.
These are example briefs, not claims that a model completed or tested the work. Read the diff and run the checks yourself.
What should you type instead?
| Speak the explanation | Type or attach the exact evidence |
|---|---|
| What you expected and what happened | @ file references and paths |
| Constraints, scope and edge cases | ! shell commands and their output |
| Why the change matters | Error messages, symbol names and flags |
Pi's !command runs a shell command and sends its output to the model, which beats reading a stack trace aloud. Do not dictate credentials or private customer data into a prompt. Speakmac transcribes on your Mac, but once you press Enter the provider you chose in Pi processes the prompt under its own policy. See Speakmac's privacy explanation for the transcription side.
What if the text does not appear, or looks wrong?
First click back into the terminal and try a short sentence. If Speakmac produced a transcript but it did not land, use Copy Last Transcript or Paste Last Transcript from History and recovery.
A long paste in Pi can look as though your words have gone. Pi collapses pastes over ten lines or 1,000 characters into a marker such as [paste #1 1240 chars]. The full text is still sent. Press Ctrl+G to open it in your external editor if you want to read or edit it first.
If Shift+Enter sends instead of adding a line, that is a terminal setting, not a dictation fault. Pi's terminal setup guide covers iTerm2, Ghostty, Apple Terminal and the VS Code terminal. If no transcript was produced at all, check the microphone and model in the Help Center.
Does Pi have its own voice input?
Not in the core. Pi leaves features like this to extensions, and the Pi package directory lists several voice add-ons. For example, rpiv-voice adds a /voice command that transcribes locally with Whisper, and pi-voice-stt records with Ctrl+R and sends audio to the speech provider you configure. They are third-party code, so read the source before installing one.
An extension is enough if Pi is the only place you dictate. A system-wide app makes more sense if you also write in your editor, browser and chat apps and want the same shortcut, custom words and on-device transcription everywhere. Speakmac is one of those; check any extension's privacy model the same way.
Try Speakmac for Mac, or see the same workflow for Claude Code and OpenCode.