To make Codex play a sound when it's done, add a Stop hook to ~/.codex/hooks.json that runs afplay /System/Library/Sounds/Glass.aiff. For approvals, add a PermissionRequest hook with a different sound. Then trust both hooks once in Codex (it asks at startup, or type /hooks). The notify setting can't do this part: it only fires when a turn completes.
Using Claude Code too? Here's how to make Claude Code play a sound when done.
Paste this into ~/.codex/hooks.json. You'll hear Glass when Codex finishes and Funk when it's waiting for your approval.
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "afplay /System/Library/Sounds/Glass.aiff >/dev/null 2>&1",
"async": true
}
]
}
],
"PermissionRequest": [
{
"hooks": [
{
"type": "command",
"command": "afplay /System/Library/Sounds/Funk.aiff >/dev/null 2>&1",
"async": true
}
]
}
]
}
}
Then start Codex. Codex asks you to review and trust new hooks the first time; follow the prompt in /hooks and trust both entries. Codex skips any hook you haven't trusted, so don't skip this step.
~/.codex/hooks.json in any editor. If it doesn't exist, create it. This is your user-level file, so it applies in every project.Stop block from the snippet above. If the file already has a "hooks" key, add Stop inside it rather than replacing the file./hooks.You can open the same review screen any time by typing /hooks. It lists every hook with its source file, command and trust state.
Codex ties trust to the exact hook definition, so every edit makes it a new hook. Change the sound or the command and you'll see the review screen again and need to trust it again.
Codex's docs say a Stop hook that exits normally should print JSON or nothing at all. Plain text counts as invalid output. afplay is quiet when it works, and the >/dev/null 2>&1 on the end keeps anything else off the screen.
If a hook does print text, Codex shows a warning under its reply that it could not accept the hook output. The sound still plays, but the warning shows up on every turn. Keep the redirect and you won't see it.
"async": true runs the command in the background, so Codex doesn't wait for the sound to finish before handing control back to you. Stop doesn't take a matcher, so it fires at the end of every turn.
The finish sound covers half of it. The other half is when Codex stops halfway through a task to ask "Would you like to run the following command?" and sits there until you come back. That's the PermissionRequest event.
"PermissionRequest": [
{
"hooks": [
{
"type": "command",
"command": "afplay /System/Library/Sounds/Funk.aiff >/dev/null 2>&1",
"async": true
}
]
}
]
The sound plays as the approval prompt appears, not after you answer it.
PermissionRequest runs when Codex is about to ask you for approval, like a shell command that needs to run outside the sandbox or a network approval. It doesn't run for commands that don't need approval, so you won't hear Funk every time Codex runs ls.
How often you hear it depends on your approval settings. If you've set Codex to never ask, this hook never fires.
The matcher filters on the tool asking for approval. To get the sound only for shell commands and not for file edits or MCP tools, add "matcher": "Bash":
"PermissionRequest": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "afplay /System/Library/Sounds/Funk.aiff >/dev/null 2>&1",
"async": true
}
]
}
]
Other values from the official Codex hooks docs include apply_patch (which also matches Edit and Write) and MCP tool names like mcp__server__tool. Leave the matcher out to cover all of them.
Running the hook in the background also means it can't approve or deny anything. It only plays the sound, and the approval prompt still waits for you.
Codex has three separate notification settings, and they don't do the same job.
hooks.json (Stop + PermissionRequest) |
[tui] notifications |
notify |
|
|---|---|---|---|
| Alert when done | Yes | Yes | Yes |
| Alert when it needs approval | Yes | Yes | No |
| Your own sound | Yes, any file afplay can play |
No, a banner or the terminal bell | Yes, it runs any command |
| Works in any terminal | Yes, it runs a shell command | Banners only in some terminals, the bell everywhere else | Yes |
| Where it goes | ~/.codex/hooks.json |
~/.codex/config.toml |
~/.codex/config.toml (user level only) |
Want different sounds for "done" and "needs approval"? Use hooks. Want a quick banner without touching JSON? Use [tui]. notify is the older option and only knows about finished turns.
Codex's terminal UI can alert you on its own, with no hooks. Add this to ~/.codex/config.toml:
# ~/.codex/config.toml
[tui]
notifications = ["agent-turn-complete", "approval-requested"]
notification_method = "auto" # auto | osc9 | bel
notification_condition = "unfocused" # or "always"
notifications can be true for everything, or a list of event types. agent-turn-complete and approval-requested are the two this page cares about.notification_method = "auto" sends a desktop notification (an OSC 9 escape code) when Codex thinks your terminal supports it, and rings the terminal bell otherwise.notification_condition = "unfocused" is the default and only alerts you when the terminal window isn't in front. Set it to "always" to get alerts while you're looking at it too.In the current Codex source, the terminals that get the OSC 9 banner in auto mode are Ghostty, iTerm2, Kitty, Warp and WezTerm. Apple's Terminal and the VS Code terminal get the bell. This list comes from the code rather than the docs, so it may change.
You don't get to pick the sound, though. It's a banner or a bell. For a real sound, use hooks.
notify runs a program when a turn finishes. It goes at the top level of ~/.codex/config.toml, above any [table]:
# ~/.codex/config.toml (top level, above any [table])
notify = ["sh", "-c", "afplay /System/Library/Sounds/Glass.aiff", "codex-notify"]
Codex adds the event details as one JSON argument at the end of the command. Pointing notify straight at afplay would hand that JSON to afplay as a second argument. Wrapping it in sh -c sidesteps that: the shell runs only the quoted command and ignores what comes after it. "codex-notify" is a placeholder name for the shell.
It has three limits:
agent-turn-complete. It can't alert you when Codex needs approval.notify in a project's .codex/config.toml and prints a startup warning. It only works in your user config.notify setting per config. If you also use the Codex desktop app, it may already have something set there, and yours would replace it. That's another reason to prefer hooks, where each event takes a list.If you set up both notify and a Stop hook, you'll hear both at the end of every turn. Pick one.
Every Mac has these in /System/Library/Sounds/:
Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink
To see the exact list on your machine:
ls /System/Library/Sounds/
To hear one before you commit to it:
afplay /System/Library/Sounds/Hero.aiff
Glass for done and Funk for needs approval works well because one is bright and the other is low. Within a day or two you'll know from across the room which one you heard.
afplay plays most audio formats. Point the hook at any file:
{
"type": "command",
"command": "afplay ~/Sounds/codex-done.mp3 >/dev/null 2>&1",
"async": true
}
Keep the clip short. A 10-second song plays to the end on every turn.
A second handler in the same group runs alongside the sound:
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "afplay /System/Library/Sounds/Glass.aiff >/dev/null 2>&1",
"async": true
},
{
"type": "command",
"command": "osascript -e 'display notification \"Done\" with title \"Codex\"' >/dev/null 2>&1",
"async": true
}
]
}
]
The first time it runs, macOS may ask whether your terminal app can send notifications. Allow it, or the banner won't show.
Rather not touch the JSON? MacYaps writes these hooks for you with one toggle. If you're sticking with the manual setup, here's what usually goes wrong.
No sound at all. Run the command yourself in a terminal:
afplay /System/Library/Sounds/Glass.aiff
If that's silent too, it's your volume or output device, not Codex.
The command works but the hook never fires. Work through these in order:
/hooks.~/.codex/config.toml for [features] with hooks = false (or the older codex_hooks = false). Delete the line or set it to true..codex/ folder. Project hooks only load when you've trusted that project. Your ~/.codex/hooks.json loads either way."async": true arrived in Codex CLI 0.148.0. That release's notes say hooks can now run commands asynchronously. Run codex --version and update if you're behind.Codex warns that it could not accept the Stop hook output. Your Stop command printed text. Add >/dev/null 2>&1 to the end of it, then trust the edited hook in /hooks.
The file has a JSON error. It almost always happens when you merge into an existing file. Look for a missing comma between blocks or a trailing comma after the last one. To check the file:
python3 -m json.tool ~/.codex/hooks.json
It prints the file back if it's valid and points at the line if it isn't.
I want a ding when Codex needs a response from me. There are two cases. If Codex asks you a question in its reply, that's the end of a turn, so the Stop sound covers it. If it's waiting on an approval prompt, that's PermissionRequest. Set up both and you'll hear one or the other.
Two sounds at the end of every turn. You probably have notify and a Stop hook both set. Remove one. /hooks also shows if the same hook lives in both ~/.codex/hooks.json and a project's .codex/ folder.
The hooks file is the same on every platform. Only the command changes.
Linux:
{
"type": "command",
"command": "paplay /usr/share/sounds/freedesktop/stereo/complete.oga >/dev/null 2>&1",
"async": true
}
Use aplay with a .wav file if you don't have PulseAudio or PipeWire.
Windows: add a commandWindows line to the same handler. Codex uses it instead of command on Windows, so one file can serve both machines:
{
"type": "command",
"command": "afplay /System/Library/Sounds/Glass.aiff >/dev/null 2>&1",
"commandWindows": "powershell -NoProfile -Command \"(New-Object Media.SoundPlayer 'C:\\Windows\\Media\\chimes.wav').PlaySync()\"",
"async": true
}
MacYaps is a Mac app, so the one-click option below is macOS only.
The hooks above work fine. Living with them gets old: the same ding hundreds of times a day, re-trusting every time you tweak a sound, and setting it all up again on every Mac you use.
MacYaps is the same hooks, written for you, with voices instead of a ding. Flip one toggle in the Agents tab and it adds them. Flip it off and it removes them cleanly. You pick a character voice pack for "needs you" and another for "done", and they shuffle so you don't tune them out. Codex can have its own packs, separate from Claude Code. If you already use MacYaps with Claude Code and imported your setup into Codex, it detects those hooks and switches Codex on for you.
Codex still asks you to trust new hooks once, so expect the review screen the first time you start Codex after turning it on.
$4.99 once, macOS 13 or later.
Add a Stop hook to ~/.codex/hooks.json that runs afplay /System/Library/Sounds/Glass.aiff. Codex asks you to review and trust new hooks the first time; follow the prompt in /hooks. Codex fires Stop at the end of every turn, so the sound plays each time it finishes.
Add a PermissionRequest hook that plays a different sound, like Funk.aiff, and trust it in /hooks. It fires when Codex is about to show an approval prompt. For a banner instead of a sound, set notifications = ["approval-requested"] under [tui] in ~/.codex/config.toml.
No. notify only fires for agent-turn-complete, which means a finished turn. For approvals, use a PermissionRequest hook or [tui] notifications with approval-requested.
Hooks run any command you like on specific events, so they can play your own sound for both "done" and "needs approval". [tui] notifications is built in and shows a desktop banner in supported terminals or rings the terminal bell, with no custom sound. notify runs a program only when a turn finishes.
Usually because it isn't trusted. Codex skips new or edited hooks until you trust them in /hooks. Also check that [features] hooks = false isn't in your config.toml, that a project hook is in a trusted project, and that you're on Codex CLI 0.148.0 or later if you use "async": true. OpenAI's 0.148.0 release notes say hooks can now run commands asynchronously: https://github.com/openai/codex/releases/tag/rust-v0.148.0.
Your user-level file is ~/.codex/hooks.json. Codex also reads hooks written inline as [hooks] tables in ~/.codex/config.toml, and the same two files inside a project's .codex/ folder.
Yes. The hooks file is the same. Swap afplay for paplay or aplay on Linux, and add a commandWindows line with a PowerShell sound command for Windows.
No. Everything on this page uses what ships with your Mac and Codex. MacYaps writes and removes the hooks for you and swaps the system sounds for character voices.