Codex CLI Notifications: How to Get a Ding When Codex Is Done or Needs Input

The Codex CLI failure mode is always the same. You hand it a task, it starts churning, and you do the sensible thing: switch to Slack, a code review, another terminal. Twenty minutes later you tab back and discover it finished four minutes in — or worse, it's been sitting at an approval prompt the whole time, waiting for a keypress that never came.

Codex doesn't announce itself. Out of the box there's no ding when it finishes and no banner when it needs input. But it does ship a hook built exactly for this — plus a couple of pragmatic workarounds when you just want a sound. Here's the full menu, from a one-line config change to a zero-config native app.

The built-in answer: the notify hook

Codex reads its configuration from ~/.codex/config.toml, and that file accepts a notify setting: an external program Codex runs when a notification-worthy event happens — most importantly when an agent turn completes, i.e. when Codex has stopped working and control is back with you.

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

That single line gives you a macOS glass "ding" every time Codex finishes a turn. The value is an argv array — first element the program, the rest its arguments — so you can point it at anything executable.

The hook is more capable than a bell, though: Codex appends a JSON payload describing the event as the final argument, including the event type and a summary of what just happened. Wire it to a small script and you get real desktop banners:

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

# ~/.codex/notify.sh
#!/bin/bash
# The last argument is a JSON blob describing the event
payload="${@: -1}"
type=$(echo "$payload" | jq -r '.type // empty')
if [ "$type" = "agent-turn-complete" ]; then
  osascript -e 'display notification "Codex is done" with title "Codex CLI"'
  afplay /System/Library/Sounds/Glass.aiff
fi

On Linux, swap osascript for notify-send and afplay for paplay. Two practical notes: the script must be executable (chmod +x), and you should test it by running it directly with a fake JSON argument before blaming Codex when nothing fires.

"I just want a ding when it needs me"

The subtler gap is the waiting for input case. The notify hook tells you when a turn ends — but when Codex pauses mid-task to ask for approval, you want the ding at that exact moment, not silence. A few options, in increasing order of effort:

• Terminal bell alerts. iTerm2 can alert you when a silent tab produces output or rings the bell; so can WezTerm and Kitty. Crude, but it catches approval prompts that print to the terminal.
• tmux monitoring. If Codex runs in a tmux window, monitor-silence and monitor-activity can flag the window when output stops or resumes — a decent proxy for "it's waiting on you."
• Newer Codex builds: hooks. Recent versions have grown a richer hooks mechanism (~/.codex/hooks.json) that can distinguish more event types, so you can play one sound for "done" and a different one for "needs approval." If you're on a current build, check the docs for what your version supports — this feature has been moving fast.

If that list made you tired, that's a reasonable reaction. Shell hooks are powerful but fiddly: they break quietly when a path changes, they're per-machine, and every teammate has to rebuild the same setup by hand.

The zero-config option

This is exactly the gap AI Done Now exists to close. It's a native macOS app that watches your Codex CLI sessions and fires a proper system notification — sound and banner — both when Codex finishes and when it's waiting for your input. No config.toml surgery, no scripts to maintain, and the same app covers Claude Code, Cursor, and other coding agents, so one install handles your whole toolbox.

The deeper win, whichever route you pick, is the workflow change: once you trust that your machine will tap you on the shoulder, you stop babysitting the terminal entirely. We wrote about that shift in a workflow that doesn't involve watching the terminal — everything there applies just as well to Codex.

Which setup should you pick?

• One sound, one minute of setup: the one-line notify + afplay config above.
• Banners and per-event sounds, and you enjoy scripting: the notify script (or hooks.json on newer builds).
• Done + waiting-for-input alerts across all your agents, zero maintenance: AI Done Now for Codex CLI.

Whatever you choose, choose something. An agent that can work unattended is only actually unattended if it can call you back — and every minute spent glancing at a scrolling terminal is a minute you paid for automation and then didn't take it.