Developer guide · macOS

How to make Codex play a sound when it's done or needs approval

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.

Last updated: October 2026 · About 2 minutes · Codex CLI on macOS

Using Claude Code too? Here's how to make Claude Code play a sound when done.

TL;DR

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.

Play a sound when Codex finishes (Stop hook)

Step by step

  1. Open ~/.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.
  2. Paste the Stop block from the snippet above. If the file already has a "hooks" key, add Stop inside it rather than replacing the file.
  3. Start Codex. Because the hook is new, Codex asks you to review and trust new hooks the first time; follow the prompt in /hooks.
  4. Give Codex a small task, switch to another window, and wait for the chime.

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.

Why Stop needs quiet output

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.

Get notified when Codex needs approval (PermissionRequest)

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.

What counts as an approval

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.

Only for shell commands: "matcher": "Bash"

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.

3 ways to get Codex notifications compared

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.

Built-in option: [tui] notifications

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"

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.

The notify setting and its limits

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:

If you set up both notify and a Stop hook, you'll hear both at the end of every turn. Pick one.

Pick a sound: macOS system sounds

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.

Use your own .mp3, .wav or .m4a

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.

Add a desktop banner too

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.

Troubleshooting

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:

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.

Windows and Linux

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.

Skip the JSON: MacYaps

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.

FAQ

How do I 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. 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.

How do I get notified when Codex needs approval on Mac?

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.

Can the Codex notify setting alert me for approvals?

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.

What's the difference between hooks.json, [tui] notifications, and notify?

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.

Why isn't my Codex hook running?

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.

Where is the Codex hooks file?

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.

Does this work on Windows or Linux?

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.

Do I need MacYaps for this?

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.

Related guides