Get notified when Codex finishes or needs approval

The Codex CLI already notifies you when its terminal isn’t focused: Ghostty, iTerm2, kitty, Warp and WezTerm show a desktop notification, and other terminals ring the bell. Choose what triggers it with tui.notifications, including approval requests. For your own sound or command, use a Stop hook for finished turns and a PermissionRequest hook for approvals. The older notify setting fires only when a turn ends. The ChatGPT desktop app and the ChatGPT phone app have their own switches.

By Dmitry Mishunin, who builds Meowdoro · October 27, 2026 · checked against the Codex documentation on October 26–27, 2026

The short answer
Built-in CLI notifications
Hooks for a sound or banner
The notify setting
ChatGPT desktop app
On your phone
Questions

The short answer

Where you use Codex	What to do
CLI in Ghostty, iTerm2, kitty, Warp, WezTerm	Nothing: you get a desktop notification while the terminal isn’t focused. Add `"approval-requested"` to `tui.notifications` if you want approvals too.
CLI in Apple’s Terminal, VS Code, Alacritty	Codex rings the bell. For a banner or sound, add a hook.
ChatGPT desktop app	Settings has separate switches for finished turns, permissions and questions.
IDE extension	No notification settings of its own; use a hook or `notify`.
Your phone	The ChatGPT app notifies you when a task on your connected computer finishes or needs you.

Built-in notifications in the CLI

Three settings in ~/.codex/config.toml control them (advanced configuration):

tui.notifications: true (the default), false, or a list of what to notify about.
tui.notification_method: auto (the default), osc9 for a desktop notification or bel for the bell. Auto uses a desktop notification where the terminal supports it and the bell elsewhere.
tui.notification_condition: unfocused (the default), so you’re only notified when you’ve switched away, or always.

~/.codex/config.toml

[tui]
notifications = ["agent-turn-complete", "approval-requested"]
notification_condition = "unfocused"

agent-turn-complete fires when Codex finishes a turn, and approval-requested when it waits for you to approve a command, an edit or an MCP server’s request. According to Codex’s source code, Ghostty, iTerm2, kitty, Warp and WezTerm get desktop notifications; Apple’s Terminal, Alacritty and the VS Code terminal get the bell.

A sound or banner with hooks

Hooks run your own command at fixed points, and they’re on by default (hooks). The two that matter for notifications:

Stop runs when a turn ends.
PermissionRequest runs when Codex is about to ask for approval. A hook that returns no decision leaves the normal approval prompt in place, so it works as a “needs you” alert.

This plays a different macOS sound for each:

~/.codex/config.toml

[[hooks.Stop]]
[[hooks.Stop.hooks]]
type = "command"
command = 'afplay /System/Library/Sounds/Tink.aiff'
timeout = 30

[[hooks.PermissionRequest]]
[[hooks.PermissionRequest.hooks]]
type = "command"
command = 'afplay /System/Library/Sounds/Ping.aiff'
timeout = 30

Trust the hooks first. Codex runs a hook only after you review and trust it: open /hooks in the CLI, or the hooks settings in the ChatGPT desktop app. Trust is tied to the hook’s contents, so after you edit a hook you trust it again.

Two details catch people out. A Stop hook must print nothing or valid JSON: plain text on standard output is an error, and a JSON {"decision":"block"} makes Codex keep working. And a PermissionRequest hook that prints a decision approves or denies for you, so keep a notification hook silent. Hooks can also live in ~/.codex/hooks.json or in a project’s .codex/ folder, which loads only in trusted projects.

For a banner instead of a sound, run osascript -e 'display notification "Codex needs you" with title "Codex"' as the command. It shows banners through Script Editor, so allow Script Editor in System Settings → Notifications if nothing appears.

The notify setting

Before hooks, Codex had a single notify setting, and it still works. It runs a program at the end of every turn and passes it a JSON argument with the turn’s details, including type, cwd and last-assistant-message:

~/.codex/config.toml

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

It has limits: it fires only for agent-turn-complete, never for approvals, and Codex ignores it in a project’s .codex/config.toml. Codex’s own code calls it legacy. For approvals, or anything new, use hooks.

In the ChatGPT desktop app

Since July 2026 the Codex app is part of the ChatGPT desktop app. Its settings let you choose when you hear about finished turns, never, only while the app is in the background, or always, with separate switches for permission requests and questions (notifications). The bell icon, or Cmd+Option+U, opens the activity view. There’s also a floating pet, opened with /pet or Option+Space, that shows whether a task is running, needs input, is ready or is blocked.

On your phone

With your Mac or PC connected, the ChatGPT app on iOS and Android notifies you when a task finishes or needs your attention, and you can approve commands from the phone (remote connections).

A quieter option: Meowdoro

We make Meowdoro, so this is a disclosure. It’s a focus timer around the MacBook notch that shows Codex sessions, in the terminal or the ChatGPT app, next to Claude Code: working, waiting for you, finished or failed. During a focus, anything that needs you slides out as one silent line; during a break agents are hidden until the next focus. It connects through Codex’s own plugin system, and Codex asks you to trust its hooks first, like any other. It also shows Codex’s 5-hour and weekly limits (how those limits work). It never approves anything. Free before December 2026, then a one-time $20, macOS 14 or later (how it connects).

Questions

Can Codex play a sound when it’s done?

Yes. Add a Stop hook that runs afplay with a sound from /System/Library/Sounds, as above, and trust it in /hooks.

Why don’t I get a notification when Codex is waiting for approval?

Either tui.notifications is a list without "approval-requested", or you rely on notify, which fires only at the end of a turn. Add the filter, or a PermissionRequest hook.

My hook doesn’t run. Why?

It probably isn’t trusted yet, or it changed since you trusted it. Open /hooks and trust it. A project’s hooks also need the project to be trusted.

Can I get notified only when the terminal isn’t focused?

That’s the default: tui.notification_condition = "unfocused". Set it to "always" to be notified even while you look at the terminal.

How do I get notified for Claude Code too?

Claude Code has its own settings and hooks; see Claude Code notifications.

Sources: the Codex documentation on configuration, hooks, notifications and remote connections, plus the Codex source code for the list of terminals, read on October 26–27, 2026. Codex changes quickly; if something here no longer matches, write to meow@meowdoro.com.