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.
Contents
- Which events notify you
- Where each alert can reach you
- Built-in Claude Code alerts: what to expect
- A tested hook for finished, needs-you, and failed
- Codex notifications: CLI, desktop app, and phone
- Why notifications don't fire: troubleshooting
- How Agentastic notifies across many agents
- Frequently asked questions
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.

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:
| Event | Built-in alert | Hook that fires |
|---|---|---|
| Finished a response | Idle alert about 60 s later, if you haven't typed | Stop, immediately |
| Needs permission | About 6 s after the prompt; each keystroke resets the wait | Notification with permission_prompt (about 6 s), or PermissionRequest (immediately) |
| Asks you a question or form | For MCP forms, about 6 s (elicitation_dialog) | Notification with elicitation_dialog |
| Failed on an API error | No alert | StopFailure (rate limit, auth, billing, server, and other errors) |
In Codex:
| Event | CLI alert (tui.notifications) | notify program | ChatGPT desktop app |
|---|---|---|---|
| Finished a turn | agent-turn-complete | Yes, the only event it gets | Turn-completion alert: never, in background, or always |
| Needs approval | approval-requested | No (we tested) | Permission alerts toggle |
| Asks you a question | Not documented | No | Question alerts toggle |
| Failed on an error | Not documented | No | Not 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 are | What reaches you | What doesn't |
|---|---|---|
| Ghostty, Kitty, iTerm2 | Built-in alerts (in iTerm2, after you allow escape-sequence alerts); hook escape sequences | Built-in alerts while you're watching the terminal, by design |
| WezTerm, Warp, Windows Terminal | Hook escape sequences: OSC 9 for WezTerm and Windows Terminal, OSC 777 for Warp | Built-in desktop alerts; "terminal_bell" gives you a bell instead |
| Apple Terminal | A silent bell when its audible bell is off; a hook can play a sound with afplay | Built-in desktop notifications |
| VS Code integrated terminal | A hook that plays a sound or runs a local notifier | Built-in alerts |
| Inside tmux | Everything above, with set -g allow-passthrough on | Everything, with passthrough off: in our test, zero alerts reached the outer terminal |
| Over SSH | Escape sequences: hook output, or built-in alerts with preferredNotifChannel set on the server | osascript, notify-send, and afplay, which run on the server |
| Your phone | Remote Control push, an ntfy post from a hook, Codex mobile, or Agentastic's iPhone app | Terminal 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".
preferredNotifChannelin~/.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+). Withon, 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:
#!/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:
{
"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:
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:
[ -n "$NTFY_TOPIC" ] && curl -s -m 5 -H "Title: $title" -d "$body" "https://ntfy.sh/$NTFY_TOPIC" >/dev/nullThe 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:
# ~/.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#
| Symptom | Cause | Fix |
|---|---|---|
| No alerts at all in Warp, VS Code, or Apple Terminal | Built-in alerts only target Ghostty, Kitty, and iTerm2 | Use the hook above (OSC 777 for Warp), or a sound hook such as afplay /System/Library/Sounds/Glass.aiff locally |
| Alerts arrive only sometimes | Built-in alerts wait until you appear away; each keystroke resets the six-second permission timer; idle alerts need 60 quiet seconds | Use Stop and Notification hooks |
| iTerm2 stays silent | Escape-sequence alerts are filtered | Settings → Profiles → Terminal → Filter Alerts → "Send escape sequence-generated alerts" |
| Nothing inside tmux | allow-passthrough is off | set -g allow-passthrough on, or all on tmux 3.4+ for background panes |
Nothing over SSH with an osascript or notify-send hook | The command runs on the server | Return a terminalSequence instead |
osascript hook does nothing on your Mac | Script Editor lacks notification permission, and Anthropic notes the failure is silent | Allow it in System Settings → Notifications, or use terminalSequence |
| Escape sequence arrives but no banner | The terminal app lacks notification permission, or Focus is on | System Settings → Notifications → your terminal |
| Hook never runs | Invalid JSON, a non-executable script, or jq missing | Run /hooks, chmod +x, and pipe a sample event through the script by hand |
Nothing with claude -p | terminalSequence works only in interactive sessions | Have the script call a notifier or curl directly |
Codex notify ignores approvals | notify receives only agent-turn-complete | Use tui.notifications with approval-requested |
Codex notify set in the repo does nothing | Project config can't set notify | Move 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.