Voice notifications for Codex CLI
Hand Codex a migration or a refactor and walk away. When the turn ends, Earpiece tells you out loud what Codex did, in one sentence. Free and open source.
What you hear
One short line at the end of each Codex turn, starting with the project:
- “billing. Migrated the invoices table.”
- “billing. Should I also migrate the invoices table?”
Running Claude Code too? Turn on Say the agent’s name under Voice and lines start with it: “Codex, billing. Migrated the invoices table.” Or give Codex its own voice under Agents → Codex → Voice.
Without API keys, Earpiece speaks the first sentence of Codex’s final message with your system voice. With an OpenAI key, or with Earpiece Pro, it writes a real one-line summary first.
Set it up in the app
- Download Earpiece and open it. The first builds are unsigned, so macOS asks you to allow it once under System Settings → Privacy & Security → Open Anyway.
- Open Agents and click Connect next to Codex. It shows Connected when it’s done. Connecting only edits the file shown there, and keeps a backup.
- Restart any Codex sessions that were already running, so they pick up the change. New sessions work right away.
- Click Test voice at the top of the Overview page to hear it.
Agents
Earpiece listens to each agent in the way that agent supports. Connecting only edits the file shown, and keeps a backup.
Any other tool can talk to Earpiece with the command line: earpiece emit --agent my-tool --type turn_end --line “Build finished”. It shows up here once it has sent something.
Make it yours in the app
| Setting | Where | What it does |
|---|---|---|
| Speak for this agent | Agents → Codex | Mutes Codex without disconnecting it. |
| Name Earpiece says | Agents → Codex | The name used when lines announce the agent. |
| Voice | Agents → Codex | A voice just for Codex, so you can tell it apart from Claude. |
| Say the agent’s name | Voice | “Codex, billing. Migrated the invoices table.” instead of just the project. |
| Quiet for a while | Quiet | Nothing is read aloud, but every update still shows in the notch. |
| Quiet hours | Quiet | Silence at night, with “Still say” to let “needs you” through. |
| Answer from the card | General | Codex approval requests show on the notch card with Allow and Deny. Off by default. |
| API keys | API Keys | Optional Smallest.ai key for natural voices, OpenAI key for summaries. |
Codex sends no start time, so every turn is announced. If that’s too chatty, use Quiet or switch Codex off with Speak for this agent. Only one line plays at a time across all your agents, and keys and tokens are redacted before a line is spoken.
Prefer the terminal?
Everything above also works from the command line. Install from source and connect only Codex:
git clone https://github.com/adissocrazy/earpiece.git
cd earpiece
node bin/earpiece.mjs install --only codex
npm link
earpiece test| Command | Same as |
|---|---|
earpiece install --chain | Keeps a notify command you already have (see below) |
earpiece voice <voice-id> --agent codex | Agents → Codex → Voice |
earpiece quiet 60 | Quiet for an hour |
earpiece answers on | General → Answer from the card |
earpiece agents | The session list on Overview |
earpiece uninstall | Disconnect for every agent, and puts your files back |
What it hooks
Earpiece sets the top-level notify command in ~/.codex/config.toml. Codex runs it after every turn with a JSON description of the turn, and Earpiece turns that into one spoken line in a background process, so Codex never waits on it.
notify = ["earpiece", "hook", "codex"]The exact command the installer writes points at your Node binary and checkout. For the full payload Codex sends, see Codex CLI notifications.
Already have a notify command?
The installer leaves it alone and tells you. earpiece install --chain keeps your command and adds Earpiece in front of it, and earpiece uninstall puts yours back. Each Codex turn is spoken once, even if your command calls Earpiece again.
Questions
Does it work with the Codex desktop app?
Yes. The Codex app runs the same notify command from ~/.codex/config.toml. Earpiece skips the hidden turn it runs to title each thread, so you only hear real work.
Does my code leave my machine?
Only if you add an OpenAI key or use Pro. Then the end of Codex’s final message is sent to write the summary, with keys and tokens removed first. Without either, nothing is sent.