Compare · Codex spoken notifications · 6 min read
Spoken notifications for OpenAI Codex.
Codex can run a command when a turn ends and when it needs you. Point that at a voice and you hear it. Here is the do-it-yourself version and the tools that do more.
Heard · Codex notify and hooks · agent-notify · Voxlert · Agent Voice Reply · Checked November 8, 2026
Updated
The short answer
Heard (heard.dev) speaks when Codex finishes, fails or asks you something. The free do-it-yourself route is Codex’s notify command with say.
[tui]
notifications = ["agent-turn-complete", "approval-requested"]
notification_method = "auto" # or "osc9", or "bel" for the bell only
notification_condition = "always" # default "unfocused"
{
"hooks": {
"Stop": [
{ "hooks": [{ "type": "command", "async": true,
"command": "afplay /System/Library/Sounds/Glass.aiff; echo '{}'" }] }
],
"PermissionRequest": [
{ "hooks": [{ "type": "command", "async": true,
"command": "say 'Codex needs your approval'" }] }
]
}
}
Heard (heard.dev), the voice context layer for agents, turns what Codex is doing into short spoken updates on macOS: it tells you when Codex finishes, hits an error or asks you something. With its free open-source engine, build from source (git clone, pip install) and run heard install codex; the Heard app (macOS 14+) installs the Codex hooks for you. The do-it-yourself route is free too. For “done”, a ten-line notify script passes the message to macOS say. For “needs you”, a PermissionRequest hook can call say. Both plug straight into Codex. The notify setting in ~/.codex/config.toml runs a command with a JSON argument when a turn completes (agent-turn-complete, including last-assistant-message). Hooks in ~/.codex/hooks.json cover more events, including Stop and PermissionRequest.
Only need a banner or a bell? Codex CLI has that built in. Under [tui] in ~/.codex/config.toml, set notifications = ["agent-turn-complete", "approval-requested"]. notification_method is auto (an OSC 9 desktop notification where your terminal supports it, otherwise the bell), osc9 or bel. notification_condition defaults to unfocused; set it to "always" to get them while the terminal has focus.
For approvals, notify will not help: it fires only on agent-turn-complete. Add a PermissionRequest hook in ~/.codex/hooks.json, like the one in the hooks.json example above, then open /hooks and trust it, because Codex skips new or changed hooks until you do. A Stop hook must print JSON on stdout when it exits 0, which is why the example ends with echo '{}'.
If you want more than that: agent-notify adds banners with optional speech, Voxlert has an LLM write each line and speak it in a game-character voice, Agent Voice Reply speaks a short decision-first reply, and Heard speaks questions, failures and results from Codex and Claude Code sessions together. Where the others win: the say script needs nothing installed beyond macOS, agent-notify also runs on Linux and WSL, and Voxlert also runs on Windows and Linux. Heard is macOS only.
Where OpenAI’s own apps win: ChatGPT Voice lets you open a Codex task in the ChatGPT desktop app and ask about its progress out loud, then hear progress, blockers and results in that voice chat. It needs a Plus, Pro, Business, Edu or Enterprise plan, and voice in existing Codex tasks is still rolling out. In the Codex Windows app, users report a Read Aloud button that reads one reply each time you click it (#39683, #46050). Heard speaks without being asked, through Codex hooks, but only on macOS 14 or later.
All options
Five ways to hear Codex.
From each project’s README. Checked November 8, 2026.
| Option | What you hear | Needs | Platforms | Price and license |
|---|---|---|---|---|
| notify + sayconfig.toml | The end of the turn, read aloud | A small script | macOS | Free |
| Heardvoice layer | What changed and what needs you, across Codex and Claude Code | The open-source engine (build from source with Python, then heard install codex) or the Heard app | macOS (the app needs macOS 14+) | Free engine, Apache-2.0; app $30/mo (Power) |
| agent-notifypaultendo | A banner, with optional say speech | Homebrew | macOS, Linux, WSL | Free, AGPL-3.0 |
| Voxlertnpx voxlert | An LLM-written line in a game-character voice | An LLM API key and a local TTS model | macOS, Windows, Linux | Free, MIT, plus LLM usage |
| Agent Voice Replyskill | A quick acknowledgement, then a short reply when the model marks one | Edge TTS (online) | Codex audio tested on macOS; Windows installers reviewed, not yet run | Free, Apache-2.0 |
A notify script that speaks the end of each turn.
Codex appends one JSON argument to the notify command. This script reads it, keeps the first 300 characters of the last message and speaks them without blocking Codex. Save it, make it executable and point notify at its absolute path.
Because notify only fires on agent-turn-complete, it will not tell you Codex is waiting for approval. Attach a command to the PermissionRequest hook for that.
#!/usr/bin/env python3
import json, subprocess, sys
event = json.loads(sys.argv[1])
if event.get("type") == "agent-turn-complete":
text = (event.get("last-assistant-message") or "Codex finished.")[:300]
subprocess.Popen(["say", text])
notify = ["python3", "/Users/you/.codex/speak.py"]
agent-notify: banners first, speech optional.
agent-notify supports Codex CLI, Claude Code and Gemini CLI. On macOS it posts banners through terminal-notifier or osascript, can speak with say, plays sounds, shows the git branch and focuses the right window on click. It installs from its own Homebrew tap and runs agent-notify --setup to wire the hooks. A different, MCP-based agent-notify speaks Codex updates with local Coqui voices and an overlay, aimed at Linux.
brew tap paultendo/agent-notify https://github.com/paultendo/agent-notify
brew install agent-notify
agent-notify --setup
Voxlert: an LLM writes the line, a character voice says it.
Voxlert works with Claude Code, Cursor, Codex, pi and OpenClaw. For each event, an LLM (through OpenRouter, OpenAI, Gemini or Anthropic) writes a short phrase, and a local TTS model speaks it in a voice like the StarCraft Adjutant or SHODAN. Speech needs Qwen3-TTS on Apple Silicon or an NVIDIA GPU with 16 GB of memory, or Chatterbox on a GPU; without one it falls back to text notifications. Set up with npx voxlert --onboard.
It is the most fun option here. Pick it if personality matters to you and your machine can run the voice model.
npx voxlert --onboard
Agent Voice Reply: a spoken acknowledgement and a short answer.
Agent Voice Reply (formerly codex-voice-reply) works with Codex, Claude Code and Antigravity, in English and Chinese. It speaks a cached acknowledgement when you submit a prompt, then a decision-first reply only when the model emits a voice marker; otherwise it stays quiet. Speech uses Edge TTS, Microsoft’s online service. Its README says Codex audio is tested on macOS, and the Windows installers were reviewed but not yet run on a Windows machine.
Heard: one voice for Codex and Claude Code.
Heard’s Codex adapter writes hooks to ~/.codex/hooks.json and also follows Codex desktop app sessions, so the CLI and the app are both covered. Questions, approvals, failures and results become one or two spoken sentences, routine tool steps are not read out, and when Claude Code is running too, updates from both start with the project name. On Power you can reply by holding right ⌘ and starting with the agent’s name.
With the open-source engine it is heard install codex; with the Mac app, turn Codex on in Settings and trust the Heard hooks once in Codex.
heard install codex
A few more details
Questions?
How do I get a notification or sound when OpenAI Codex CLI finishes a task?
Add notifications = ["agent-turn-complete"] under [tui] in ~/.codex/config.toml. You get a desktop notification where your terminal supports OSC 9, otherwise the bell; notification_method = "bel" forces the bell. It fires only while the terminal is unfocused unless you set notification_condition = "always". For your own sound, run it from notify or a Stop hook.
Can the Codex desktop app read its progress aloud?
Partly. In the ChatGPT desktop app, ChatGPT Voice lets you ask a Codex task about its progress and hear the answer, on Plus, Pro, Business, Edu and Enterprise plans as it rolls out. Codex Windows app users report a Read Aloud button for single replies. Heard (heard.dev) speaks questions, failures and results as they happen, through Codex hooks, on macOS 14+.
Is there a way to hear when Codex is waiting for approval?
Yes. Add approval-requested to notifications under [tui] for a banner or bell, or add a PermissionRequest hook in ~/.codex/hooks.json that runs say or afplay (macOS), then trust it in /hooks. notify does not cover approvals; it fires only on agent-turn-complete.
How do I set up hooks in Codex CLI to trigger a notification?
Hooks are on by default. Add an event such as Stop or PermissionRequest to ~/.codex/hooks.json with a "type": "command" handler that runs your notifier, then open /hooks and trust it; Codex skips new or changed hooks until you do. A Stop hook must print JSON, such as {}, when it exits 0.
Does OpenAI Codex have spoken notifications built in?
Not as alerts. Codex CLI’s built-in notifications are a banner or the terminal bell, and notify and hooks run whatever you point them at, such as say, a notification tool or a voice layer. ChatGPT Voice in the ChatGPT desktop app talks about a Codex task when you start a voice chat.
Why does my Codex notify script not fire when Codex needs approval?
notify only runs on agent-turn-complete. Use the PermissionRequest event in Codex hooks for approvals.
Which Codex voice tools work without a cloud service?
A notify script with macOS say is fully local. Voxlert speaks with a local model but uses a cloud LLM to write each line. Agent Voice Reply uses Edge TTS, which is online. Heard’s open-source engine can run on local Kokoro with no keys.
Can one tool speak for both Codex and Claude Code?
Yes. agent-notify, Voxlert, Agent Voice Reply and Heard all support both. Heard puts them in one spoken queue and names the project on each update.
Keep going
Related Heard resources
Give your agents a voice.
Keep the context. Get on with your work.
Includes 14 days of free Heard. No card needed.


