Ambient › Guides

How to get notified when Codex finishes or needs approval on Mac

Updated September 27, 2026 · 5 min read

Codex can alert you on its own: turn on notifications under [tui] in ~/.codex/config.toml and it sends an OSC 9 desktop notification in terminals that support it, or rings the bell. For a custom alert, point notify at a program that Codex runs after every turn. For a live status across sessions and the Codex app, use Ambient.

Which option should you use?

Option 1: Codex's built-in TUI notifications

The Codex CLI can raise a notification itself. In auto mode it prefers the OSC 9 escape sequence, which iTerm2, Ghostty, Kitty and WezTerm turn into a desktop notification, and falls back to the terminal bell.

# ~/.codex/config.toml
[tui]
notifications = true
notification_method = "auto"          # or "osc9", "bel"
notification_condition = "unfocused"  # or "always"

To alert on only some events, give a list instead of true: notifications = ["agent-turn-complete", "approval-requested"]. With "unfocused", the default, Codex stays quiet while its terminal is in front. Inside tmux, add set -g allow-passthrough on to ~/.tmux.conf so the escape sequence reaches your terminal. In iTerm2, also enable escape-sequence alerts under Settings › Profiles › Terminal › Filter Alerts.

Option 2: The notify program, or Codex hooks

notify: run a program after every turn

notify takes a command as an array. Codex runs it when an agent turn completes and passes one JSON argument with fields such as type ("agent-turn-complete"), cwd and last-assistant-message.

# ~/.codex/config.toml, above every [table]
notify = ["bash", "-c", "osascript -e 'display notification \"Codex finished a turn\" with title \"Codex\"'"]

Keep it above [tui] and any other table. In TOML, a key written after a table header belongs to that table, and Codex won't see it. notify fires only for finished turns, not for approvals.

Hooks: react to approvals too

Codex also loads lifecycle hooks from ~/.codex/hooks.json (or a project's .codex/hooks.json). Events include PermissionRequest and Stop, so you can alert on both:

// ~/.codex/hooks.json
{
  "hooks": {
    "PermissionRequest": [
      { "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Codex needs approval\" with title \"Codex\"'" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }] }
    ]
  }
}

Codex asks you to trust new hooks: type /hooks inside Codex once and approve them. As with any osascript notification, macOS files it under Script Editor, so allow Script Editor in System Settings › Notifications, and expect a click to open Script Editor.

Option 3: Ambient, for the CLI and the Codex app

Ambient is a free Mac app that turns Codex's hooks into a status at the notch: a green orb while Codex works, an amber pulse when it needs approval, a check when it's done and red when a turn fails. Banners and chimes come only for those moments.

1. Download Ambient from yaml.cafe and drag it to Applications.
2. Open it and click Connect All. Ambient backs up ~/.codex/hooks.json and adds its own entries, leaving yours alone.
3. Type /hooks in Codex once and approve Ambient's hooks.

Each hook runs in the background, finishes in about 15 ms, and sends a few short fields over a Unix socket on your Mac. A click on the island or a banner opens the exact thread in the Codex app, the exact tab in Terminal or iTerm2, or the exact pane in tmux. Ambient shows Claude Code and Gemini CLI sessions in the same place.

Common questions

Why doesn't my Codex notify program run?

In TOML, every key after a [table] header belongs to that table. Put notify = [...] near the top of ~/.codex/config.toml, before [tui], [mcp_servers] or any other table. Also check that the program is executable and that its path is absolute.

Can notify tell me when Codex needs approval?

No. notify currently fires only for agent-turn-complete. For approvals, use the built-in TUI notification, a PermissionRequest hook in ~/.codex/hooks.json, or Ambient, which shows an amber "needs you" state.

Do these work with the Codex desktop app?

The tui settings apply to the Codex CLI. Ambient works with both the Codex CLI and the Codex app, and a click on an Ambient notification opens the exact thread in the Codex app.

Why did my new Codex hooks do nothing?

Codex asks you to trust new hooks before it runs them. Type /hooks inside Codex and approve them, then restart sessions that were already open.

Sources

• Advanced configuration: notifications and hooks, Codex docs
• Configuration reference, Codex docs

More guides: Claude Code notifications on Mac · Gemini CLI notifications on Mac