See when Codex needs your approval, or finishes (Mac).

Here are four ways Codex can alert you on a Mac. A turn is one round of work: you send a message, Codex works, then it stops and waits for you. A hook is a command Codex runs at a set moment, such as just before it asks for your approval.

A common mix-up is to set notify and then wait for an approval alert that never comes. OpenAI's configuration docs say notify fires only for agent-turn-complete for now. For approvals, use one of the other three rows.

Codex's terminal notifications are on by default, so you may already get them. They fire only when the terminal (the app where Codex runs, such as Terminal or iTerm2) is not the app in front. To choose the events yourself, set them in your config file.

Add to ~/.codex/config.toml. If the file already has a [tui] section, put these keys under it; don't add a second [tui] header. The terminal list in the comment comes from Codex's source code, not its docs (see below).

[tui]
notifications = ["agent-turn-complete", "approval-requested"]
notification_method = "auto"        # osc9 in iTerm2/Ghostty/Kitty/Warp/WezTerm; bel elsewhere
notification_condition = "unfocused" # or "always"

With notification_method set to auto, Codex picks how to signal: osc9 sends a special code (an escape sequence) that some terminals turn into a desktop notification, and bel rings the terminal bell. Set notification_condition to "always" if you want alerts even while you are looking at the terminal.

Why Terminal only rings a bell.

OpenAI's docs don't name the terminals that show a banner. Codex's public source code (so this can change) sends the banner sequence to Ghostty, iTerm2, Kitty, Warp and WezTerm, and a plain bell to every other terminal, including the Terminal app that comes with macOS. A bell alone makes no banner. In Terminal, Settings > Profiles > Advanced > Bell offers a visual bell, a Dock badge and a Dock icon that bounces while the window is in the background. For a real banner in Terminal, use the hook further down.

Inside tmux, Codex's banner sequence only gets through when allow-passthrough is turned on: with on, only from a pane you can see; with all, from hidden panes too (tmux manual). Add this line to ~/.tmux.conf, or write all instead of on to get alerts from hidden panes:

set -g allow-passthrough on

notify runs one program when a turn completes and hands it the details as a single JSON argument. It works the same in any terminal. OpenAI's example uses terminal-notifier, a third-party Homebrew tool that doesn't come with macOS. The script below uses only what ships with macOS: it shows the start of Codex's last reply and the project folder, and plays the Glass sound.

Step 1. Save this as a new file, ~/.codex/notify-macos.js:

// Codex notify -> macOS banner + sound. Codex appends one JSON argument.
function run(argv) {
  var n = {};
  try { n = JSON.parse(argv[argv.length - 1] || "{}"); } catch (e) {}
  if (n.type && n.type !== "agent-turn-complete") return;
  var app = Application.currentApplication();
  app.includeStandardAdditions = true;
  var msg = String(n["last-assistant-message"] || "Turn complete").slice(0, 180);
  var folder = String(n.cwd || "").split("/").pop();
  app.displayNotification(msg, { withTitle: "Codex finished", subtitle: folder, soundName: "Glass" });
}

Step 2. Add this line to your existing ~/.codex/config.toml, above the first [section] header. Replace YOUR_NAME with the name of your home folder: Codex runs this list as written, so ~ is not expanded (from Codex's source code, not its docs).

notify = ["/usr/bin/osascript", "-l", "JavaScript", "/Users/YOUR_NAME/.codex/notify-macos.js"]

If no banner appears, open System Settings > Notifications. Anthropic's hooks guide says banners sent with osascript are listed there under Script Editor, which you must allow, and that macOS won't ask you first. The name you see may differ on your Mac.

Hooks give you a real approval banner in any terminal, Terminal included. Codex runs a PermissionRequest hook just before it asks you to approve something, and a Stop hook when a turn finishes. PermissionRequest does not fire for commands that need no approval.

Merge into ~/.codex/hooks.json. If the file exists, don't replace it: other tools may keep their entries there (Cowork Island does, once you switch Codex on in it). Add each entry below to the matching list inside "hooks", create the list if it is missing, and keep each entry in its own braces.

{
  "hooks": {
    "PermissionRequest": [
      { "hooks": [ { "type": "command", "async": true, "timeout": 10,
        "command": "/usr/bin/osascript -e 'display notification \"Codex needs your approval\" with title \"Codex\" sound name \"Funk\"' >/dev/null 2>&1" } ] }
    ],
    "Stop": [
      { "hooks": [ { "type": "command", "async": true, "timeout": 10,
        "command": "/usr/bin/osascript -e 'display notification \"Codex finished\" with title \"Codex\" sound name \"Glass\"' >/dev/null 2>&1" } ] }
    ]
  }
}

1. Save the file, open Codex and type /hooks.
2. Trust both new entries. Codex skips new or changed hooks until you trust them, so an untrusted hook looks broken.
3. Keep the >/dev/null 2>&1 ending: a Stop hook must print JSON or nothing.

For a spoken line or a phone alert instead, the notify setup generator builds the entry in your browser and names the file it goes in.

Since 9 July 2026, the Codex app is part of the ChatGPT desktop app on macOS. Its alerts live in the app, not in config files:

• Settings > Notifications (Cmd+,): show turn-completion alerts never, only while ChatGPT is in the background, or always, with separate switches for permission and question notifications.
• Sound: one notification sound for finished tasks, permission requests and questions. Choose Default, Classic or None; on macOS a system sound or a file you import also works.
• Activity: where it is available, the bell in the sidebar, or Cmd+Option+U, lists chats that are unread, running or waiting for you.

The [tui] keys above are for Codex in a terminal. OpenAI's docs don't say whether notify or your own hooks run for chats in the desktop app, so don't count on them there.

• OpenAI: Advanced configuration
• OpenAI: Configuration reference
• OpenAI: Sample configuration
• OpenAI: Hooks
• OpenAI: Notifications
• OpenAI: Settings reference
• OpenAI: Changelog
• openai/codex source code (terminal list only)
• Apple: Terminal profile Advanced settings
• Apple: Displaying notifications
• tmux manual
• Anthropic: Claude Code hooks guide (Script Editor)

Sources checked 18 October 2026. This guide is written by Cowork Island's maker. For corrections, email support@coworkisland.com or open an issue on GitHub.