Codex CLI notifications: get alerted when it finishes or needs approval

Option 1: Codex's built-in TUI notifications

The Codex TUI notifies you out of the box when a turn ends, when it asks to run a command or edit files, and when a Plan mode prompt or a question is waiting. It sends an OSC 9 desktop notification in terminals that support it and rings the bell in the rest, and by default only while the terminal is unfocused. Tune it under [tui] in ~/.codex/config.toml:

[tui]
notifications = ["agent-turn-complete", "approval-requested"]
notification_method = "auto"      # or "osc9", "bel"
notification_condition = "always" # default "unfocused"

What you get: alerts in this machine's terminal only, and nothing on your phone. Whether you hear anything depends on the terminal; to make Codex ding when it needs approval, see the sound guide.

Option 2: Codex's notify command in config.toml

Codex CLI can run an external program through the notify setting in ~/.codex/config.toml. Codex currently sends it one event, agent-turn-complete, as a JSON argument with fields such as thread-id, last-assistant-message, and input-messages. Your script turns that into a toast, sound, or push. Codex ignores notify in a project's .codex/config.toml, so set it in your user config:

notify = ["python3", "/Users/you/codex-notify.py"]

What you get: turn-complete alerts only, with whatever your script does. Approval prompts are not covered by notify, which is the moment you most need to hear about.

Option 3: Codex hooks (Stop and PermissionRequest)

Codex CLI 0.144 and newer ship a hooks system modelled on Claude Code's. Hooks live in ~/.codex/hooks.json and are on by default in current releases (early ones needed hooks = true under [features] in config.toml). Stop fires when the turn ends. PermissionRequest fires when Codex is about to ask for approval, and only then. A hook entry looks like this:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "notify-send \"Codex\" \"Turn complete\"", "timeout": 10 }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          { "type": "command", "command": "notify-send -u critical \"Codex\" \"Needs approval\"", "timeout": 10 }
        ]
      }
    ]
  }
}

Option 4: anotifier, one command for Codex and every other agent

npx anotifier@latest setup

The wizard detects ~/.codex, writes Stop, PermissionRequest, and SessionStart hooks into ~/.codex/hooks.json, enables the hooks feature flag, records the trust hashes in config.toml, and backs up hooks.json first. A finished turn arrives as my-app · Codex at default priority; an approval request arrives urgent, on your desktop and phone, so the run never sits blocked while you are in another window. The approval path is proven in CI by driving the real Codex TUI through a permission modal.

anotifier is free, open source (AGPL-3.0), has zero dependencies, and uninstalls cleanly with anotifier uninstall. Full reference in the docs.

Codex CLI notifications on Windows

Codex CLI runs natively on Windows and keeps its settings in %USERPROFILE%\.codex: CODEX_HOME defaults to ~/.codex. The built-in notification works as described in Option 1, with one catch. With notification_method = "auto", Codex sends OSC 9 only to Ghostty, iTerm2, Kitty, Warp, and WezTerm. Windows Terminal and the VS Code terminal are not on that list, so Codex rings the bell (BEL) there and no desktop notification appears. That is how Codex CLI 0.163.0, the latest release at the time of writing, behaves.

• Windows Terminal decides what the bell does. Its bellStyle setting accepts audible (the default), window, taskbar, all, and none. Microsoft documents all as a sound plus a flashing taskbar icon, and says that when the terminal is not in focus only the taskbar icon flashes. Codex notifies only while the window is unfocused by default, so check what your bellStyle does in the background.
• The VS Code terminal handles the bell through its accessibility.signals.terminalBell setting. If you hear nothing, check that setting.

To change it for every profile, set bellStyle under profiles.defaults in Windows Terminal's settings.json:

{
  "profiles": {
    "defaults": { "bellStyle": "all" }
  }
}

For a real Windows notification, use a hook. Codex hooks accept commandWindows, an optional Windows-only replacement for command, and by default Codex starts a hook through cmd.exe /C. This version needs no module install. It reuses the Windows PowerShell 5.1 toast from the WSL toast guide. Save it as %USERPROFILE%\.codex\win-toast.ps1:

param(
  [string]$Title = 'Codex',
  [string]$Message = 'Done'
)
$ErrorActionPreference = 'Stop'
$null = [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime]
$null = [Windows.UI.Notifications.ToastNotification, Windows.UI.Notifications, ContentType = WindowsRuntime]
$AppId = '{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\WindowsPowerShell\v1.0\powershell.exe'
$xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)
$texts = $xml.GetElementsByTagName('text')
$null = $texts.Item(0).AppendChild($xml.CreateTextNode($Title))
$null = $texts.Item(1).AppendChild($xml.CreateTextNode($Message))
$toast = [Windows.UI.Notifications.ToastNotification]::new($xml)
[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($AppId).Show($toast)

Then add this to %USERPROFILE%\.codex\hooks.json. The command entries are the Linux fallback and commandWindows runs on Windows; delete either one you don't need:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send \"Codex\" \"Turn complete\"",
            "commandWindows": "powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"%USERPROFILE%\\.codex\\win-toast.ps1\" -Title Codex -Message \"Turn complete\"",
            "async": true
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send -u critical \"Codex\" \"Needs approval\"",
            "commandWindows": "powershell.exe -NoProfile -ExecutionPolicy Bypass -File \"%USERPROFILE%\\.codex\\win-toast.ps1\" -Title Codex -Message \"Needs approval\"",
            "async": true
          }
        ]
      }
    ]
  }
}

• Open /hooks in Codex and trust the two new hooks, or Codex skips them.
• The toast shows under the name Windows PowerShell, with the title and message you pass and no agent icon, custom sound, or click-to-focus. If nothing appears, Do not disturb (Focus Assist) may be on.
• For a sound file instead of a toast, use the commandWindows sound hook in the guide to making Codex ding when it needs approval.

To skip the wiring, run npx anotifier@latest setup in PowerShell. On Windows it writes Stop, PermissionRequest, and SessionStart hooks into %USERPROFILE%\.codex\hooks.json, turns on the hooks feature flag, records the trust hashes in config.toml, and backs up hooks.json first. It then checks for PowerShell 7 (pwsh) and installs the BurntToast module for your user with Install-Module BurntToast -Scope CurrentUser; if pwsh is missing it prints winget install --id Microsoft.PowerShell --source winget. Toasts then arrive as my-app · Codex with the Codex icon and a Windows notification sound, and clicking one brings the terminal window forward. anotifier test toast confirms it works. The Windows and WSL guide has the details, including click-to-focus and a fix table for toasts that do not show.

Codex running inside WSL is the Linux build: it reads ~/.codex in the distribution, so run npx anotifier@latest setup inside WSL. The toast then goes through Windows interop. See how the WSL toast reaches Windows and Windows toast from WSL. Codex also runs in VS Code's terminal; the VS Code page covers what changes over Remote-SSH and in dev containers.

Turn off or mute Codex CLI notifications

Codex has several independent alerts, so pick the switch that matches the one you hear. To silence Codex's built-in notifications, put this in ~/.codex/config.toml:

[tui]
notifications = false

Try it

One command wires Codex CLI and every other agent you have installed.

npx anotifier@latest setup

Other guides

Claude CodeCursorGemini CLIClaude Code permissionsClaude Code soundsClaude Code usage limitsClaude Code auto-compactClaude Code hooks securityccnotifyCodex CLI soundsAntigravity CLIWindows & WSLmacOS & LinuxAgent hooksTroubleshootingntfy phone pushWSL Windows toast