Codex notifications: get alerted when it finishes or waits for approval
Codex can tell you when a turn is finished and when it needs your approval. The catch: the two mechanisms in the config file cover different events, and on most terminals “desktop notification” quietly becomes a bell.
SHORT ANSWER
Use the [tui] section: notifications = ["agent-turn-complete", "approval-requested"], and notification_condition = "always" if you want alerts even while the terminal is focused. Codex sends a desktop notification (OSC 9) only in Ghostty, iTerm2, Kitty, Warp and WezTerm. Everywhere else, including Windows Terminal, it rings the bell. The top-level notify setting runs your own program, but only for agent-turn-complete, never for approvals.
Two different settings
| [tui] notifications | notify | |
|---|---|---|
| What it does | Terminal alert from the Codex CLI | Runs a program you choose |
| Turn complete | Yes (agent-turn-complete) | Yes (agent-turn-complete) |
| Approval requested | Yes (approval-requested) | No |
| Plan / question prompts | Yes (plan-mode-prompt, async-question) | No |
| Default | On | Off |
If you want to know when Codex is waiting for you, notify alone will never do it. Use the TUI notifications for that.
TUI notifications
This is the relevant part of OpenAI’s sample configuration:
notifications:true,false, or a list of events.approval-requestedcovers command, file-edit and MCP approval requests.notification_condition: by default alerts fire only when the terminal is not focused. Setalwaysif you keep the terminal visible on another monitor.notification_method:auto,osc9orbel.
The messages look like “Approval requested: <command>”, “Codex wants to edit <file>” and “Agent turn complete”.
Why you only hear a beep (Windows Terminal and others)
In auto mode, Codex sends a desktop notification (the OSC 9 escape sequence) only when it recognizes Ghostty, iTerm2, Kitty, Warp or WezTerm. Every other terminal (Windows Terminal, the VS Code terminal, Apple Terminal) gets the terminal bell. This comes from Codex’s source code (tui/src/notifications/mod.rs); the docs only say auto “prefers OSC 9”.
On Windows Terminal you can make the bell more noticeable: set bellStyle to all in the profile settings to play a sound and flash the taskbar icon (the default is audible).
You can also force notification_method = "osc9"; whether your terminal turns it into a system notification depends on the terminal.
Run your own program with notify
notify runs an external program when a turn completes and passes one JSON argument with type, thread-id, turn-id, cwd, input-messages and last-assistant-message. That makes it good for a phone push, a webhook or a log: anything beyond the terminal. It is a top-level key, so put it above any [section]:
A minimal script, following the one in OpenAI’s docs:
- A project’s
.codex/config.tomlcannot setnotify. It has to be in your user config. - Codex’s source code marks
notifyas legacy and plans to replace it with hooks. It works today; keep an eye on the changelog.
What about hooks?
Codex has hooks too. They are on by default and include PermissionRequest and Stop events, configured in ~/.codex/hooks.json or a [hooks] table, and every non-managed hook has to be reviewed and trusted with /hooks before it runs. There is no Notification event, and OpenAI’s docs don’t show a notification hook. For alerts, the TUI setting above is the documented path.
The Codex app and the IDE extension
The Codex desktop app has its own controls: turn-complete alerts can be set to never, only while the app is in the background, or always, and separate switches turn permission and question notifications on or off. The IDE extension has no notification settings of its own. OpenAI’s docs point you to notify instead.
If you approve from your phone through the ChatGPT app, issue #39346 reports a case where the phone shows “approval waiting” without a card to answer it.
Seeing it, and answering it
A bell tells you something happened in some terminal. Pet Island shows Codex on a small island at the top of your screen (working, waiting or done), and when Codex asks to run a command or edit a file, the request appears there with the command or the diff. Allow or deny it without switching windows; for questions, one click takes you to the right terminal. It works with the Codex CLI and the Codex app, next to Claude Code, Cursor and your other agents.
FAQ
How do I get a notification when Codex finishes?
Codex’s TUI notifications are on by default for agent-turn-complete, but by default only fire when the terminal isn’t focused. Set notification_condition = "always" in [tui] if you want them while it is focused.
How do I get notified when Codex needs approval?
Add "approval-requested" to notifications in the [tui] section of ~/.codex/config.toml. The notify setting does not fire for approvals.
Why does Codex only beep instead of showing a notification?
In auto mode Codex sends a desktop notification only in Ghostty, iTerm2, Kitty, Warp and WezTerm. Other terminals, including Windows Terminal, get the bell.
Can I put notify in my project’s .codex/config.toml?
No. Project config cannot set notify; put it in ~/.codex/config.toml.
Does Codex have a Notification hook?
No. Codex hooks include PermissionRequest and Stop, but there is no Notification event and no documented notification hook.
Sources
Every setting and behavior on this page was checked against these pages on October 26, 2026. Agents change fast; if something no longer matches, the official page wins.
- OpenAI: Codex sample config
- OpenAI: Codex advanced config (notify)
- OpenAI: Codex notifications
- OpenAI: Codex hooks
- openai/codex source: tui/src/notifications/mod.rs
- openai/codex source: tui/src/chatwidget/notifications.rs
- Issue #39346: Mobile shows approval waiting but no approval card
- Microsoft Learn: Windows Terminal profile settings (bellStyle)