DEV Community

Great Work
Great Work

Posted on Originally published at taskhold.com

Why Codex CLI waits for approval without telling you, and the fix

#ai #codex #cli #tutorial

Originally published at taskhold.com.

Short answer: Codex alerts you by default, but only when its terminal is unfocused, and only Ghostty, iTerm2, Kitty, Warp and WezTerm get a desktop notification. Other terminals get a bell. Set tui.notification_condition to always, pick a method, or add a PermissionRequest hook. For questions about the work, have Codex post to a shared board such as Taskhold's live board.

You give Codex a long task, switch to something else, and come back to find it stopped on an approval prompt a few minutes in. Codex has alerts on by default; whether one reaches you depends on window focus, your terminal and the kind of event. This guide covers why it happens, the config that fixes it, and how to cut down on prompts.

For the wider picture of a running agent, see how to see what your coding agent is doing. To try answering a blocked agent from a browser, open the live board demo. If the footer says "Waiting for startup" instead, Codex is still starting an MCP server: see Codex stuck on Waiting for startup.

Why there was no alert

Codex's terminal UI sends a notification when it needs you: approval-requested covers command, edit and MCP approvals, and separate types cover a finished turn (agent-turn-complete), a plan mode prompt and a question. These settings decide whether you see it:

  • tui.notification_condition defaults to unfocused, so nothing fires while the Codex terminal window has focus.
  • tui.notification_method defaults to auto. In the Codex source, auto sends an OSC 9 desktop notification only in Ghostty, iTerm2, Kitty, Warp and WezTerm. Apple Terminal, the VS Code terminal, Windows Terminal, GNOME Terminal, Konsole and Alacritty get a plain bell character, which may be silent depending on the terminal's bell settings.
  • Inside tmux, Codex wraps the notification for tmux to pass through, and tmux forwards it only with allow-passthrough on.
  • The notify setting runs your program only on agent-turn-complete, so a notify script never fires for an approval prompt.

Fix 1: change the notification settings

Add this to ~/.codex/config.toml:

[tui]
notifications = true
notification_condition = "always"
notification_method = "bel"
Enter fullscreen mode Exit fullscreen mode

Use "osc9" instead of "bel" if your terminal shows OSC 9 notifications. notifications also takes a list such as ["approval-requested", "agent-turn-complete"].

In Apple Terminal, turn on Audible bell under Settings > Profiles > Advanced to hear the bell. For tmux, add set -g allow-passthrough on to ~/.tmux.conf and run tmux source-file ~/.tmux.conf.

Fix 2: a desktop notification from a hook

A PermissionRequest hook runs when Codex is about to ask for approval, such as a sandbox escalation, a network request or an MCP tool call that needs approval. It works in any terminal. On macOS, put this in ~/.codex/hooks.json:

{
  "hooks": {
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Codex is waiting for approval\" with title \"Codex\"'",
            "async": true
          }
        ]
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode

No matcher means every approval request. async keeps the hook from delaying the prompt. On Linux use notify-send 'Codex' 'Codex is waiting for approval'.

Codex runs a new hook only after you review and trust it, so open /hooks once and trust this one. The hook prints no decision, so the normal approval prompt still appears. If nothing shows on macOS, allow Script Editor in System Settings > Notifications: osascript sends through it.

Fix 3: fewer prompts to wait on

  • The default Auto preset (workspace-write sandbox, on-request approvals) asks only to edit outside the workspace or to use the network. /permissions switches presets mid-session, and /status shows the current policy and writable folders.
  • approvals_reviewer = "auto_review" sends eligible approval requests to a reviewer agent instead of to you. It denies critical-risk actions, and /approve retries one recent denial. Reviews use extra model calls.
  • For MCP tools, default_tools_approval_mode on a server, or approval_mode on one tool, sets when Codex asks: auto, prompt, writes or approve.
  • --ask-for-approval never removes prompts but keeps the sandbox, so blocked actions fail instead of waiting. --dangerously-bypass-approvals-and-sandbox (--yolo) removes both, and OpenAI doesn't recommend it.

Fix 4: approve from your phone

The ChatGPT mobile app can follow Codex tasks on a computer you connect through the ChatGPT desktop app (Settings > Connections > Control this Mac or PC), approve requested commands and send new instructions. Availability depends on rollout and your workspace settings, and the computer has to stay awake and online.

Where Taskhold fits

Taskhold handles the other kind of stop: a question about the work. With the workflow snippet in AGENTS.md, Codex calls taskhold_block with one specific question instead of waiting in the terminal. The task moves to the top of the live board under Needs you, an open board tab can show a desktop notification, and you reply from any browser, including your phone. Codex reads the reply with taskhold_updates and can take the next task while it waits.

If you need a decision from me, call taskhold_block on the task with one
specific question, then take the next todo. Check taskhold_updates between
steps for my reply.
Enter fullscreen mode Exit fullscreen mode

Add to AGENTS.md, next to the Taskhold workflow snippet from the Codex setup page.

FAQ

Does Codex notify me by default?

Yes. tui.notifications is on by default, but notifications fire only when the terminal is unfocused, and terminals other than Ghostty, iTerm2, Kitty, Warp and WezTerm get a bell instead of a desktop notification.

Why doesn't my notify script fire for approvals?

notify runs only on agent-turn-complete. Use tui.notifications for approval-requested, or a PermissionRequest hook to run your own command when Codex is about to ask.

Can a project's config set notify?

No. Codex ignores notify in a project's .codex/config.toml and prints a startup warning. Put it in ~/.codex/config.toml.

Codex says "Waiting for startup". Is that an approval prompt?

No. It means you sent a prompt while Codex was still starting, usually while an MCP server connects. Codex sends it once startup finishes, or when the server's startup timeout (10 seconds by default) runs out. Esc cancels the send. See Codex stuck on Waiting for startup.

Sources

Related

About Taskhold

Taskhold is a hosted task list shared by a person and their AI coding agents over MCP. Agents break tasks into steps and report progress, and the person watches a live board. $12/month or $120/year per person, 7-day trial with a card, no free plan. Made by Great Work LLC.

Top comments (0)