---
title: "Codex Notifications Explained: notify, Hooks, MCP"
description: "What Codex notify, TUI notifications and hooks each do, why a ping misses your phone, and how an MCP question lets you answer Codex from it."
url: "https://notifexapp.com/blog/codex-notifications-explained"
published: "2026-11-19"
updated: "2026-11-19"
author: "Alaa Jawhar"
---

# Codex Notifications Explained: notify, Hooks or an MCP Question

Codex notifications come in three kinds. The `notify` setting runs your own program when a turn ends. TUI notifications ping the terminal when a turn ends or Codex needs approval. Hooks run scripts at points such as Stop and PermissionRequest. All three send a message out. None of them carries your answer back to Codex.

If you want Codex to ask you on your phone and continue with your reply, you need a tool that asks and waits. That is an MCP server such as Notifex. The step-by-step setup is on the [Codex setup page](https://notifexapp.com/codex). This post explains what each built-in option does, why a ping sometimes never reaches you, and when an MCP question is the better fit. Facts about Codex come from OpenAI's docs, read 2026-11-19.

## What notifications does Codex have built in?

The [Codex advanced configuration docs](https://learn.chatgpt.com/docs/config-file/config-advanced) describe two settings. `notify` runs an external program, and Codex passes it one JSON argument. `tui.notifications` is built into the terminal UI and can be limited to event types such as `agent-turn-complete` and `approval-requested`.

Two more settings shape the TUI ping. `tui.notification_method` takes `auto`, `osc9` or `bel`. `tui.notification_condition` takes `unfocused` or `always`. The [configuration reference](https://learn.chatgpt.com/docs/config-file/config-reference) says the condition defaults to `unfocused`.

![The Notifications section of the Codex advanced configuration docs, with the notify setting and an example notify.py script.](https://d29bihfk9mha1v.cloudfront.net/notifex/blog-codex-notifications-explained-codex-1-v1.webp)

_Codex advanced configuration docs at learn.chatgpt.com, captured 2026-11-19. Apps and logos belong to their owners._

_Codex notification options (OpenAI Codex docs, read 2026-11-19) and an MCP question_

| Option | Fires when | Reaches you | Can you answer from it? |
| --- | --- | --- | --- |
| notify in ~/.codex/config.toml | A turn completes (agent-turn-complete only) | Wherever your script sends it | No, it runs your program and stops |
| tui.notifications | Turn complete or approval requested, by default only while the terminal is unfocused | The terminal on your computer | No, you answer in the terminal |
| Stop hook | A turn stops | Wherever your hook script sends it | No, unless you build the reply path |
| PermissionRequest hook | Codex is about to show an approval prompt | Wherever your hook script sends it | The hook can allow or deny, by its own rules |
| MCP question (Notifex ask_question) | Codex decides it needs a person | A push on your iPhone or Android phone | Yes, the answer is the tool result |

## How does the notify setting work?

You point `notify` at a command, written as an array, for example `notify = ["python3", "/path/to/notify.py"]`. Codex runs it with a single JSON argument when a turn completes. The docs list the common fields: `type`, `thread-id`, `turn-id`, `cwd`, `input-messages` and `last-assistant-message`.

The example script in the docs exits unless `type` is `agent-turn-complete`, then shows a macOS notification with `terminal-notifier`. Two details trip people up:

- **Only one event.** `agent-turn-complete` is the only supported event, so notify will not tell you that Codex is waiting for approval.
- **User config only.** A project `.codex/config.toml` cannot set notify. Put it in `~/.codex/config.toml`.

To reach your phone, make the script post to a push service instead of a desktop banner. With ntfy that is one HTTP request, as the [ntfy publishing docs](https://docs.ntfy.sh/publish/) show. We compare that route in [ntfy vs Pushover for AI coding agents](https://notifexapp.com/blog/ntfy-vs-pushover-for-ai-agents).

## What can Codex hooks add?

Hooks run scripts or MCP tools at fixed points in a session. The [Codex hooks docs](https://learn.chatgpt.com/docs/hooks) list events such as PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, Stop, SessionStart and SessionEnd. You define them in `hooks.json` or in inline `[hooks]` tables in `config.toml`, at user level or inside a repository.

Two events matter for notifications. **Stop** runs when a turn stops, so it can send a done ping. **PermissionRequest** runs when Codex is about to ask for approval, before the prompt appears. It can allow or deny the request, or let the normal approval flow continue. Project hooks load only when the project's `.codex/` layer is trusted.

A PermissionRequest hook decides by rules you write. If you want a person to make that call from a phone, you build the round trip yourself. Send the request out, wait, read the reply and return it. That is the plumbing an MCP question already includes.

## Why do Codex notifications not reach your phone?

Most missing pings have one of these causes:

1. **The TUI ping is local.** tui.notifications use OSC 9 or a terminal bell. They show up on the computer that runs the terminal, never on your phone.
2. **The terminal was focused.** With the default `unfocused` condition, the TUI stays quiet while you look at it. Set `always` to change that.
3. **notify sits in the wrong file.** A project config cannot set it. Move it to `~/.codex/config.toml`.
4. **The script ignores its argument.** notify passes the JSON as one argument. A script that reads stdin sees nothing.
5. **You expected an approval ping from notify.** It only fires on agent-turn-complete. Use the TUI setting or a PermissionRequest hook for approvals.

## How do you answer Codex from your phone?

Give Codex an MCP tool that asks a person. Notifex is a remote MCP server for that job. Codex calls **ask_question**, your phone gets a push, and the call waits until someone answers. Your answer returns to Codex as the tool result, and the run continues.

1. [Install Notifex on your iPhone](https://notifexapp.com/iphone-app) or [Android phone](https://notifexapp.com/android-app). It is free on both stores.
2. Create a project and copy its secret key. It is shown once.
3. Add a `[mcp_servers.notifex]` table to `~/.codex/config.toml` and set `NOTIFEX_API_KEY` in your shell.
4. Run `codex mcp list` and check that notifex is enabled.
5. Tell Codex in `AGENTS.md` when to ask you and when to send a done message.

`[mcp_servers.notifex]` `url = "https://mcp.notifexapp.com/mcp"` `bearer_token_env_var = "NOTIFEX_API_KEY"` `tool_timeout_sec = 3600`

The `tool_timeout_sec` line matters. The [Codex MCP docs](https://learn.chatgpt.com/docs/extend/mcp) give a 60 second default for a tool call, and ask_question waits until you answer. One hour gives you time. For longer waits, Codex can ask with `wait=false`, get a question id back at once, and check later with check_answer. The question stays open in your inbox either way.

![A terminal showing a demo ~/.codex/config.toml with notify, tui.notifications and a Notifex MCP server, then codex mcp list showing notifex enabled.](https://d29bihfk9mha1v.cloudfront.net/notifex/blog-codex-notifications-explained-codex-2-v1.webp)

_Codex CLI 0.154.0 in a terminal on a Mac, demo home folder and project, captured 2026-11-19._

The full walkthrough, with the shell line for your key and an AGENTS.md snippet, is on the Notifex page for Codex. The same server works in other clients too. If you also run Claude Code, the [Claude Code setup](https://notifexapp.com/claude-code) uses the same endpoint, and [the setup page for every client](https://notifexapp.com/connect-your-agent) lists the rest.

## Can Codex tell you it is done and also ask?

Yes. Keep a built-in ping for "done", and use the MCP question for "which one?". Codex can also send a plain update with **send_message** when it finishes. That message lands in the same thread on your phone, next to any question it asked.

- **Turn finished, nothing to decide:** notify or a Stop hook, sent to a desktop banner or a push service.
- **Waiting on an approval while you sit nearby:** tui.notifications with approval-requested.
- **A decision Codex should not guess:** ask_question, so your phone buzzes and Codex waits for your answer.
- **Several decisions at once:** ask_questions sends up to 10 questions in one push.

![Three iPhone screens numbered 1 to 3: a Notifex push on the home screen, a question with two options, and the answered thread.](https://d29bihfk9mha1v.cloudfront.net/notifex/blog-codex-notifications-explained-codex-3-v1.webp)

_Notifex on an iPhone 17 Pro simulator with demo fixture data, captured October 2026._

## Which option should you set up first?

Start with the place you will be when Codex stops. At your desk, the TUI setting is enough. Away from it, a notify script that posts to a push service tells you a turn ended. When Codex needs a real decision, an MCP question is the only option here that brings your answer back without extra code.

A common setup uses two of them. notify sends a short done ping. Notifex handles questions, and its thread keeps a record of who answered what. For the same split in Claude Code, see [Claude Code notification when done](https://notifexapp.com/blog/claude-code-notification-when-done).

## Quick answers

### Does Codex have a notification when it is done?

Yes. Set notify in ~/.codex/config.toml to run a program on agent-turn-complete, or turn on tui.notifications for a terminal ping.

### Can notify tell me Codex is waiting for approval?

No. notify only fires on agent-turn-complete. Use tui.notifications with approval-requested, or a PermissionRequest hook.

### Why does Codex stop waiting for my answer after a minute?

Codex gives MCP tool calls 60 seconds by default. Raise tool_timeout_sec for the Notifex server, or ask with wait=false and check back with check_answer.

### Where is the full Codex setup for Notifex?

On the Notifex page for Codex at /codex. It has the config.toml table, the shell line for your key and an AGENTS.md snippet.
