Codex Sound When Done: Make Codex CLI Play a Sound When It Finishes

Sometimes you don't want banners, dashboards, or a notification center full of agent chatter. You want one thing: a sound when Codex is done. You kick off a task, you go read something else, and a ding tells you the terminal wants you back. This post is only about that — getting Codex CLI to make a sound when it finishes, on macOS, Linux, and Windows, from the simplest possible one-liner to a setup with different sounds for different events.

The one-liner: afplay in the notify hook

Codex CLI has no built-in "play sound on finish" toggle, but it has something better: a notify setting in ~/.codex/config.toml that runs any program you like when a turn completes. Point it at your operating system's audio player and you have your ding:

# ~/.codex/config.toml
notify = ["bash", "-c", "afplay /System/Library/Sounds/Glass.aiff"]

afplay is macOS's built-in audio player, and Glass.aiff is the classic soft ding. Save the file, start a new Codex session, and every completed turn now announces itself. Nothing to install, one line of config.

One gotcha catches nearly everyone: in TOML, root-level keys must appear before any table sections. If your config.toml already has sections like [tui] or [mcp_servers.something], the notify line must go above them — put it at the top of the file. If your sound never fires, this is the first thing to check.

Picking a better sound

Every macOS system sound lives in /System/Library/Sounds/ — run ls /System/Library/Sounds/ and audition them with afplay. Popular choices for "task done": Glass.aiff (gentle), Hero.aiff (triumphant), Ping.aiff (minimal), and Funk.aiff (impossible to miss). You can also point afplay at any audio file of your own — a two-second mp3 works fine — and control loudness with the volume flag: afplay -v 0.5 file.aiff plays at half volume, which your open-plan office neighbours will appreciate.

Linux and Windows equivalents

The pattern is identical; only the player changes.

• Linux (PulseAudio/PipeWire): notify = ["bash", "-c", "paplay /usr/share/sounds/freedesktop/stereo/complete.oga"]
• Linux (ALSA): use aplay with a wav file instead.
• Windows (WSL or native PowerShell): notify = ["powershell.exe", "-c", "[console]::beep(880,300)"] gives a simple beep; for a real sound, use (New-Object Media.SoundPlayer 'C:\Windows\Media\notify.wav').PlaySync().

Only ding when the task is actually done

The bare one-liner plays for every notification event Codex emits. That is usually what you want, but if you'd rather filter, Codex appends a JSON payload as the final argument to whatever program notify runs. The payload's type field is agent-turn-complete when a turn ends, so a tiny script can play your done-sound only for that event:

# ~/.codex/config.toml
notify = ["bash", "/Users/you/.codex/ding.sh"]

# ~/.codex/ding.sh  (chmod +x it)
#!/bin/bash
payload="${@: -1}"
if echo "$payload" | grep -q '"type":"agent-turn-complete"'; then
  afplay /System/Library/Sounds/Glass.aiff
fi

Using grep keeps the script dependency-free; if you have jq installed, parsing properly is nicer. The payload also includes a summary of what Codex just did, which is how people build full desktop-banner setups on top of the same hook.

The sound you actually need: "it's waiting on you"

Here is the uncomfortable truth about done-sounds: the expensive silence isn't after a task finishes — it's when Codex stops mid-task to ask for approval and sits there while you read Slack. The notify hook fires when a turn completes, which covers many of these pauses, but terminal-level tricks can close the gap: iTerm2, WezTerm, and Kitty can all alert when a quiet tab produces output, and tmux's monitor-silence flags a window that has gone still. We dug into this specific problem in our post on getting a ding when Codex needs a response.

If you'd rather not maintain shell scripts

Config edits and ding scripts are genuinely fine for one machine and one tool. They get old when you also run Claude Code and Cursor, when a path change silently breaks the script, or when you want "done" and "waiting for input" to sound different without writing a JSON parser in bash.

Either way, the destination is the same: a terminal you can walk away from. Set up the sound once — one line of TOML or one app install — and Codex stops being something you watch and starts being something that calls you when it matters.