Claude Code Notifications: Why They Don't Fire and How to Fix Them

Which events notify, where each alert can reach you, and a hook script we tested on finish, permission, and failure.

9 min read

Claude Code shows its own desktop notifications out of the box only in Ghostty, Kitty, and iTerm2, and only when you appear to be away: about six seconds into an unanswered permission prompt, or about 60 seconds after it finishes. To be told the moment it finishes in any terminal, over SSH, or inside tmux, add a Stop hook and a Notification hook that hand Claude Code an escape sequence to print. The script below does that, and we tested it on finish, permission, and failure. Codex CLI is separate: turn on tui.notifications in ~/.codex/config.toml.

A ringing desk bell alerts an engineer as one ghost agent finishes a task and another raises a hand for permission.

We ran every test here on November 14 and 15, 2026, with Claude Code 2.1.325, Codex CLI 0.167.2, and tmux 3.6a on macOS, and we captured the raw bytes each tool sent to the terminal. Agentastic publishes this guide. The last section covers how Agentastic notifies across many agents; everything before it works without Agentastic.

Which events notify you#

The first question is not "which terminal" but "which event". Finishing, needing permission, and failing are separate events with different timing, and each tool exposes a different set. In Claude Code:

EventBuilt-in alertHook that fires
Finished a responseIdle alert about 60 s later, if you haven't typedStop, immediately
Needs permissionAbout 6 s after the prompt; each keystroke resets the waitNotification with permission_prompt (about 6 s), or PermissionRequest (immediately)
Asks you a question or formFor MCP forms, about 6 s (elicitation_dialog)Notification with elicitation_dialog
Failed on an API errorNo alertStopFailure (rate limit, auth, billing, server, and other errors)

In Codex:

EventCLI alert (tui.notifications)notify programChatGPT desktop app
Finished a turnagent-turn-completeYes, the only event it getsTurn-completion alert: never, in background, or always
Needs approvalapproval-requestedNo (we tested)Permission alerts toggle
Asks you a questionNot documentedNoQuestion alerts toggle
Failed on an errorNot documentedNoNot documented

Sources: Anthropic's hooks reference and terminal guide; OpenAI's notifications and advanced configuration pages. Two details trip people up. Claude Code's Notification event does not fire when Claude finishes; it fires for the idle reminder a minute later, and only if you haven't typed. And Stop does not fire when you interrupt Claude, or when a turn ends in an API error, which is what StopFailure is for.

Where each alert can reach you#

The second question is delivery. An alert is either an escape sequence printed into the terminal stream, which your terminal turns into a notification, or a command that runs on whichever machine runs the agent:

Where you areWhat reaches youWhat doesn't
Ghostty, Kitty, iTerm2Built-in alerts (in iTerm2, after you allow escape-sequence alerts); hook escape sequencesBuilt-in alerts while you're watching the terminal, by design
WezTerm, Warp, Windows TerminalHook escape sequences: OSC 9 for WezTerm and Windows Terminal, OSC 777 for WarpBuilt-in desktop alerts; "terminal_bell" gives you a bell instead
Apple TerminalA silent bell when its audible bell is off; a hook can play a sound with afplayBuilt-in desktop notifications
VS Code integrated terminalA hook that plays a sound or runs a local notifierBuilt-in alerts
Inside tmuxEverything above, with set -g allow-passthrough onEverything, with passthrough off: in our test, zero alerts reached the outer terminal
Over SSHEscape sequences: hook output, or built-in alerts with preferredNotifChannel set on the serverosascript, notify-send, and afplay, which run on the server
Your phoneRemote Control push, an ntfy post from a hook, Codex mobile, or Agentastic's iPhone appTerminal escape sequences

Built-in Claude Code alerts: what to expect#

According to Anthropic's terminal guide, Claude Code sends a desktop notification when it detects Ghostty, Kitty, or iTerm2; a silent bell in Apple Terminal when that profile's audible bell is off; and nothing in other terminals, which the guide says includes Warp and the VS Code integrated terminal.

Three settings change that:

  • iTerm2 needs its alerts turned on: Settings → Profiles → Terminal, check "Notification Center Alerts", then "Filter Alerts" → "Send escape sequence-generated alerts".
  • preferredNotifChannel in ~/.claude/settings.json (shown as "Local notifications" in /config) forces a channel: "auto", "terminal_bell", "iterm2", "iterm2_with_bell", "kitty", "ghostty", or "notifications_disabled". Over SSH outside tmux, set it on the server to your local terminal's value.
  • tmux needs set -g allow-passthrough on (tmux 3.3+). With on, only the pane you are looking at can send alerts; all (tmux 3.4+) lets background panes send them too.

Built-in alerts are designed not to interrupt you while you're watching, which is exactly why they feel unreliable when you've switched to another window right next to the terminal. If you want an alert every time, use hooks.

A tested hook for finished, needs-you, and failed#

Hooks run without a terminal of their own, so a hook that writes an escape sequence to /dev/tty fails. Anthropic's answer is the terminalSequence output field: the hook returns the sequence as JSON, and Claude Code prints it. Because Claude Code prints it to its own terminal, it travels over SSH like any other output.

This script extends Anthropic's example to all three events and strips control characters from the message so a stray newline can't break the sequence. It needs jq. Save it as ~/.claude/hooks/notify.sh:

bash
#!/usr/bin/env bash # ~/.claude/hooks/notify.sh: alert when Claude Code finishes, fails, or needs you. # Works locally and over SSH. Requires jq. input=$(cat) # Read a field from the hook input, flatten control characters, cap the length. field() { jq -r "($1) // \"\" | tostring | [explode[] | if . < 32 or . == 127 then 32 else . end] | implode | .[0:160]" <<<"$input" } case "$(field .hook_event_name)" in Stop) title="Claude Code finished"; body=$(field '.last_assistant_message // "Done"') ;; StopFailure) title="Claude Code stopped"; body=$(field '.last_assistant_message // .error') ;; Notification) title=$(field '.title // "Claude Code needs you"'); body=$(field .message) ;; *) exit 0 ;; esac # Hooks have no terminal of their own, so hand Claude Code an escape sequence to print. # It reaches your local terminal even over SSH. # 777: Ghostty, Warp, urxvt. 9: iTerm2, WezTerm, Windows Terminal. 99: Kitty. case "${CLAUDE_NOTIFY_OSC:-777}" in 9) seq=$(printf '\033]9;%s: %s\007' "$title" "$body") ;; 99) seq=$(printf '\033]99;;%s: %s\033\\' "$title" "$body") ;; *) seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body") ;; esac jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

Make it executable with chmod +x ~/.claude/hooks/notify.sh. If your terminal is iTerm2, WezTerm, or Windows Terminal, add export CLAUDE_NOTIFY_OSC=9 to your shell profile; for Kitty, use 99. Then register it in ~/.claude/settings.json, merging with any hooks you already have:

json
{ "hooks": { "Stop": [{ "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/notify.sh" }] }], "StopFailure": [{ "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/notify.sh" }] }], "Notification": [ { "matcher": "permission_prompt|elicitation_dialog", "hooks": [{ "type": "command", "command": "$HOME/.claude/hooks/notify.sh" }] } ] } }

The matcher leaves out idle_prompt on purpose: Stop already tells you when Claude finished, and the idle reminder a minute later would repeat it. Run /hooks inside Claude Code to confirm all three are loaded. You can test the script without starting Claude:

bash
echo '{"hook_event_name":"Stop","last_assistant_message":"Tests pass"}' | ~/.claude/hooks/notify.sh # {"terminalSequence":"\u001b]777;notify;Claude Code finished;Tests pass\u0007"}

What we saw in live sessions. A one-line prompt produced a Stop event with last_assistant_message set to Claude's reply, and the terminal received ESC]777;notify;Claude Code finished;OK. In manual permission mode, asking Claude to create a file raised a permission dialog; about six seconds later a Notification event arrived with notification_type: "permission_prompt" and the message "Claude needs your permission", and the alert followed. Pressing Esc to deny it produced no Stop event, matching Anthropic's note that interrupts don't fire it. Starting Claude with a model name that doesn't exist produced a StopFailure with error: "model_not_found", and the script turned Claude's error message into a "Claude Code stopped" alert. Inside a nested tmux session, the same alert reached the outer terminal only after allow-passthrough was turned on.

Two limits apply. Claude Code prints terminalSequence only in interactive sessions, so claude -p and the Agent SDK ignore it. And if you need the permission alert immediately rather than after six seconds, Anthropic recommends a PermissionRequest hook instead; we didn't test that variant.

Add a phone push with ntfy#

ntfy turns an HTTP POST into a phone notification. To also push from the hook, add this line just before the final jq line, and set NTFY_TOPIC in your shell profile:

bash
[ -n "$NTFY_TOPIC" ] && curl -s -m 5 -H "Title: $title" -d "$body" "https://ntfy.sh/$NTFY_TOPIC" >/dev/null

The public server has no sign-up, so ntfy's docs say the topic name works like a password; pick something long and unguessable. The message text, including the end of Claude's reply, leaves your machine, so send only the title if that matters. We checked the request shape against a local listener, not ntfy.sh's servers.

Codex notifications: CLI, desktop app, and phone#

Codex has two independent switches in ~/.codex/config.toml. tui.notifications makes the interactive CLI alert your terminal; notify runs a program of your choice. OpenAI's configuration guide says the program currently receives only agent-turn-complete:

toml
# ~/.codex/config.toml. notify must sit above any [table]. notify = ["python3", "/Users/you/.codex/notify.py"] [tui] notifications = ["agent-turn-complete", "approval-requested"] # or true for all notification_method = "auto" # auto, osc9, or bel notification_condition = "unfocused" # or "always"

In auto, Codex prefers OSC 9 and falls back to a bell. Codex CLI 0.168.0 added osc777, according to the release notes. Put notify in your user config: the same guide lists it among the keys Codex ignores, with a startup warning, in a project's .codex/config.toml. Exact key types are in the config reference.

What we saw. With notification_method = "osc9" and notification_condition = "always", a finished turn sent ESC]9;OK to the terminal and called the notify program with JSON like {"type":"agent-turn-complete","cwd":"…","last-assistant-message":"OK","thread-id":"…"}. A command that needed approval sent ESC]9;Approval requested: /bin/zsh -lc 'touch codex-a...' right away, but did not call notify at all. So use tui.notifications for approvals and notify for completion webhooks. One quirk: in 0.167.2, notify also fired once for a background turn that named the thread, with a different thread-id and a JSON title as its message, so filter on thread-id if you forward these.

In the ChatGPT desktop app, Codex settings choose turn-completion alerts (never, only in the background, or always) and separate permission and question alerts, and the Activity view (Command-Option-U on macOS) lists them. Codex on the web has its own notification settings. On a phone, Codex on mobile in the ChatGPT iOS app controls a connected Mac or Windows PC, which must stay awake and online.

Why notifications don't fire: troubleshooting#

SymptomCauseFix
No alerts at all in Warp, VS Code, or Apple TerminalBuilt-in alerts only target Ghostty, Kitty, and iTerm2Use the hook above (OSC 777 for Warp), or a sound hook such as afplay /System/Library/Sounds/Glass.aiff locally
Alerts arrive only sometimesBuilt-in alerts wait until you appear away; each keystroke resets the six-second permission timer; idle alerts need 60 quiet secondsUse Stop and Notification hooks
iTerm2 stays silentEscape-sequence alerts are filteredSettings → Profiles → Terminal → Filter Alerts → "Send escape sequence-generated alerts"
Nothing inside tmuxallow-passthrough is offset -g allow-passthrough on, or all on tmux 3.4+ for background panes
Nothing over SSH with an osascript or notify-send hookThe command runs on the serverReturn a terminalSequence instead
osascript hook does nothing on your MacScript Editor lacks notification permission, and Anthropic notes the failure is silentAllow it in System Settings → Notifications, or use terminalSequence
Escape sequence arrives but no bannerThe terminal app lacks notification permission, or Focus is onSystem Settings → Notifications → your terminal
Hook never runsInvalid JSON, a non-executable script, or jq missingRun /hooks, chmod +x, and pipe a sample event through the script by hand
Nothing with claude -pterminalSequence works only in interactive sessionsHave the script call a notifier or curl directly
Codex notify ignores approvalsnotify receives only agent-turn-completeUse tui.notifications with approval-requested
Codex notify set in the repo does nothingProject config can't set notifyMove it to ~/.codex/config.toml

How Agentastic notifies across many agents#

One agent in one terminal is easy to watch. With five agents in five worktrees, the problem changes from "tell me when it's done" to "tell me which one needs me, and stop telling me about the ones I've seen". That is what Agentastic's notifications are built around:

  • One inbox for every agent. Each event becomes a durable entry. The pane that owns it gets a colored ring: blue for finished, orange for blocked on input or permission, red for failed. The agent's terminal or Agent Chat tab shows a status dot, and the toolbar bell counts what's unread.
  • Alerts only when you're elsewhere. If you're already looking at the agent's terminal, the event goes straight into history with no banner, sound, badge, or ring. A macOS notification appears only while Agentastic is in the background.
  • Clearing that matches the urgency. A finished ring clears after you look at the pane for about a second. A blocked or failed one stays until you act: type, click, reply in Chat, or mark it as seen.
  • Jump to the next one. Shift-Command-U (Navigate → Next Agent Needing Attention) takes you to the next agent waiting on you.
  • No hook setup. In Agentastic's terminals, Claude Code's lifecycle hooks are injected for you, so you don't edit ~/.claude/settings.json. The hooks pass along state and identity, not your prompt text. Codex sessions are tracked from Codex's own session events.
  • Remote and phone. Agents on SSH machines report to the same inbox, dev notify --title "Deploy done" works from any script or agent in an Agentastic terminal, local or remote, and the iPhone app gets an end-to-end encrypted push when an agent finishes, fails, or needs permission. For agents running in Chat, the notification offers Allow Once and Deny.

Two limits, so you aren't surprised. Agentastic's terminal doesn't turn OSC 9 or 777 sequences into notifications, so inside Agentastic use the built-in tracking or dev notify rather than the hook script above. And red Error states depend on the agent reporting a failure. Codex stream errors do, but Agentastic doesn't install Claude Code's StopFailure hook, so don't count on a red ring for a Claude API error such as a rate limit.

For the full model, read the notifications docs. If you run several Claude Code sessions, running multiple Claude Code agents in parallel covers the rest of the setup, and the terminal roundup compares how terminals handle alerts. For Codex specifically, see Codex app vs CLI. To try the inbox, download Agentastic for macOS.

Frequently asked questions#

How do I get notified when Claude Code finishes?#

Add a Stop hook. Claude Code runs it as soon as the main agent finishes responding, and a hook that returns a terminalSequence turns that into a desktop notification in terminals such as Ghostty, iTerm2, Kitty, WezTerm, and Warp, locally or over SSH.

Why am I not getting Claude Code notifications?#

Out of the box, Claude Code only sends desktop notifications to Ghostty, Kitty, and iTerm2, and only when you appear to be away: about six seconds into a permission prompt or about 60 seconds after it finishes. tmux also drops them unless allow-passthrough is on.

What is the difference between the Stop and Notification hooks?#

Stop fires as soon as Claude finishes responding. Notification fires when Claude Code would alert you: a permission prompt after about six seconds, an MCP form, or an idle reminder about 60 seconds after it finished. Use Stop for done and Notification for needs-you.

How do I turn on Codex CLI notifications?#

Set tui.notifications in ~/.codex/config.toml, and optionally notification_method (auto, osc9, or bel) and notification_condition (unfocused or always). The separate notify program runs only when a turn completes; in our test it did not run for an approval request.

Can I get Claude Code notifications on my phone?#

Yes. Remote Control can push to the Claude app on subscription plans, a hook can post to an ntfy topic, and Agentastic's iPhone app receives encrypted pushes when agents finish, fail, or need permission.

Do Claude Code notifications work over SSH?#

Yes, if the alert travels as an escape sequence. Return a terminalSequence from a hook, or set preferredNotifChannel on the server to your local terminal's type. Commands like osascript or notify-send run on the server, so you never see them.

How does Agentastic notify across many agents?#

It keeps one inbox for every agent, rings the pane that needs you (blue for finished, orange for blocked, red for failed), sends a macOS notification only while the app is in the background, and jumps to the next agent needing attention with Shift-Command-U.