<!-- Generated from the same content as https://heard.dev/compare/codex-spoken-notifications. -->

# Spoken Notifications for OpenAI Codex: Heard, notify, Hooks, Voxlert and agent-notify (2026)

Source: https://heard.dev/compare/codex-spoken-notifications

Hear when OpenAI Codex finishes or needs approval: Heard speaks it on macOS, or use the notify command with say. Also agent-notify, Voxlert, Agent Voice Reply.

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 October 18, 2026

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.

~/.codex/config.toml · built-in banner or bell (Codex CLI)

```
[tui]
notifications = ["agent-turn-complete", "approval-requested"]
notification_method = "auto"        # or "osc9", or "bel" for the bell only
notification_condition = "always"   # default "unfocused"
```

~/.codex/hooks.json · sound when done, voice when approval is needed (macOS; merge into your existing file, then trust it in /hooks)

```
{
  "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`](https://learn.chatgpt.com/docs/config-file/config-advanced) setting in `~/.codex/config.toml` runs a command with a JSON argument when a turn completes (`agent-turn-complete`, including `last-assistant-message`). [Hooks](https://learn.chatgpt.com/docs/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](https://learn.chatgpt.com/docs/features/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](https://github.com/openai/codex/issues/39683), [#46050](https://github.com/openai/codex/issues/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.

- **notify + say config.toml:** What you hear: The end of the turn, read aloud; Needs: A small script; Platforms: macOS; Price and license: Free
- **Heard voice layer:** What you hear: What changed and what needs you, across Codex and Claude Code; Needs: The open-source engine (build from source with Python, then `heard install codex`) or the Heard app; Platforms: macOS (the app needs macOS 14+); Price and license: Free engine, Apache-2.0; app $30/mo (Power)
- **agent-notify paultendo:** What you hear: A banner, with optional `say` speech; Needs: Homebrew; Platforms: macOS, Linux, WSL; Price and license: Free, AGPL-3.0
- **Voxlert npx voxlert:** What you hear: An LLM-written line in a game-character voice; Needs: An LLM API key and a local TTS model; Platforms: macOS, Windows, Linux; Price and license: Free, MIT, plus LLM usage
- **Agent Voice Reply skill:** What you hear: A quick acknowledgement, then a short reply when the model marks one; Needs: Edge TTS (online); Platforms: Codex audio tested on macOS; Windows installers reviewed, not yet run; Price and license: Free, Apache-2.0

(1) Do it yourself

## 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.

~/.codex/speak.py

```
#!/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])
```

~/.codex/config.toml

```
notify = ["python3", "/Users/you/.codex/speak.py"]
```

**Use the absolute path**

Replace `/Users/you` with your home folder, and run `chmod +x ~/.codex/speak.py` once.

**Optional: skip the script**

If you would rather not maintain a script, the Heard app installs the Codex hooks for you (macOS 14 or later); in Codex CLI, trust the Heard hooks once when prompted. The script above stays the free, no-account option.

(2) agent-notify

## agent-notify: banners first, speech optional.

[agent-notify](https://github.com/paultendo/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](https://github.com/H4sh3/agent-notify) speaks Codex updates with local Coqui voices and an overlay, aimed at Linux.

Terminal · agent-notify

```
brew tap paultendo/agent-notify https://github.com/paultendo/agent-notify
brew install agent-notify
agent-notify --setup
```

(3) Voxlert

## Voxlert: an LLM writes the line, a character voice says it.

[Voxlert](https://github.com/settinghead/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.

Terminal · Voxlert

```
npx voxlert --onboard
```

(4) Agent Voice Reply

## Agent Voice Reply: a spoken acknowledgement and a short answer.

[Agent Voice Reply](https://github.com/chemny/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.

(5) Heard

## 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.

Terminal · Heard open-source engine

```
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

[**Text-to-speech for Claude Code** say hook, narrator plugins, VoiceMode and Heard.](https://heard.dev/compare/claude-code-text-to-speech) [**terminal-notifier for coding agents** Banners for Claude Code and Codex, and their limits.](https://heard.dev/compare/terminal-notifier-for-coding-agents) [**Heard for Codex** How the Codex integration works.](https://heard.dev/integrations/openai-codex) [**All comparisons** Every Heard comparison page in one place.](https://heard.dev/compare)

## Give your agents a voice.

Keep the context. Get on with your work.

[Download for Mac](https://heard.dev/download/use-cases?format=dmg)

Includes 14 days of free Heard. No card needed.
