How to Get Notified When Your Coding Agent Finishes or Needs You
Updated October 30, 2026 · first published August 20, 2026 · by the AQ team
Claude Code and Codex send separate signals for a finished turn, a turn waiting on you, and a turn that failed, and each one needs its own alert. In Claude Code, use a Notification hook for "needs you", the Stop hook for "finished", and StopFailure for a turn that ended on an API error. In Codex, the notify program and a Stop hook cover completion, while approvals come from the TUI notification setting or a PermissionRequest hook. A turn ending only means the agent stopped responding, so word every alert as "open the session", never "it worked". This guide gives copyable configuration for both CLIs, a routing script you can test against a local mock, and the security limits of sending agent events to a phone, checked against vendor documentation on October 30, 2026.
Three events, three alerts
- Needs you. The agent is waiting on an approval or an answer. Nothing moves until you respond, so this is the one alert worth interrupting for.
- Finished a turn. The agent stopped responding. A diff may be waiting, but the work has not been checked: the tests could be red and the change could be wrong.
- Failed turn. The turn ended on an error such as a rate limit or an authentication problem. Claude Code reports this as a separate event. Codex documents no equivalent, so after a long Codex run, look at the session even when no alert arrived.
Send "needs you" and "failed" to a loud channel, and send "finished" to a quiet one, or you will mute the channel within a day.
Claude Code: the built-in notification
When Claude finishes a task or pauses for a permission prompt and you appear to be away from the terminal, it fires a notification event. What you see is controlled by the preferredNotifChannel setting, which appears in /config as "Local notifications". The default is auto, and the accepted values are auto, terminal_bell, iterm2, iterm2_with_bell, kitty, ghostty, and notifications_disabled. With auto, Claude Code sends a desktop notification in iTerm2, Ghostty, and Kitty, rings the bell in Apple Terminal only when that profile's audible bell is off, and does nothing in other terminals. To get a bell character in any terminal:
{
"preferredNotifChannel": "terminal_bell"
}
Three details matter on remote machines. The desktop notification travels over SSH to your local terminal. Ghostty and Kitty forward it to the OS notification center without setup, while iTerm2 needs Settings, Profiles, Terminal, then "Notification Center Alerts" checked and "Send escape sequence-generated alerts" enabled under "Filter Alerts". Inside tmux, notifications never reach the outer terminal until you add passthrough to ~/.tmux.conf and run tmux source-file ~/.tmux.conf:
set -g allow-passthrough on
Third, a hook runs whether or not the built-in notification is on: even notifications_disabled changes only how you are alerted, not whether your hook fires. If nothing appears, also confirm the terminal application has notification permission in your OS settings.
Claude Code hooks: which event answers which question
Hooks are commands Claude Code runs at lifecycle events. They run alongside the built-in notification, so you can keep both. The events that matter for alerts, as documented on October 30, 2026:
| Event or matcher | Fires when | Use it for |
|---|---|---|
| Notification, permission_prompt | Claude needs approval for a tool use or a sandboxed command's network request, and the prompt has waited about six seconds. In a terminal each keystroke defers it, and it fires only when you appear to be away. | Needs you |
| Notification, elicitation_dialog and elicitation_url_dialog | An MCP server opens a form or asks you to open a URL, and you have not typed for about six seconds. | Needs you |
| PermissionRequest (its own event) | Claude Code is about to ask you for permission. It runs immediately, without the six-second wait. | Needs you, with no delay |
| Notification, idle_prompt | Claude finished responding about 60 seconds ago, you have not typed since, and no background agent is still running. | A late reminder |
| Stop | The main agent finished responding. It does not run when you interrupt, and API errors fire StopFailure instead. | Finished a turn |
| StopFailure | The turn ended on an API error. The payload carries an error type such as rate_limit, authentication_failed, billing_error, or server_error. | Failed turn |
| Notification, agent_needs_input and agent_completed | A background session needs input, or finishes or fails, and only while agent view is open in a terminal. agent_needs_input also covers an agent team teammate's setup question (v2.1.248 or later) and auto mode's classifier-charge notice. | Background sessions only |
The last row is the one that surprises people. An ordinary foreground session never emits agent_completed, so a Notification hook with that matcher stays silent for it. Use Stop for "finished". The Stop payload also includes last_assistant_message and a background_tasks list, so a script can tell a session that is done from one paused while background work runs. In sessions hosted through the Agent SDK, such as Claude Desktop and the VS Code extension, permission_prompt fires about six seconds after the request and is not deferred by typing, and it did not fire at all before v2.1.233. Set CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS to 1 to turn it off there.
Notification and StopFailure hooks cannot block anything, and their exit codes and output are ignored, so a broken command fails quietly. The troubleshooting section below shows how to catch that.
A minimal Claude Code configuration
This registers one routing script for the three events. It uses no matcher on Notification because the script ignores the types you do not want, and the next section is that script.
{
"hooks": {
"Notification": [{ "hooks": [{ "type": "command", "command": "/home/you/bin/route-agent-event.sh claude" }] }],
"Stop": [{ "hooks": [{ "type": "command", "command": "/home/you/bin/route-agent-event.sh claude" }] }],
"StopFailure": [{ "hooks": [{ "type": "command", "command": "/home/you/bin/route-agent-event.sh claude" }] }]
}
}
If your settings file already has other keys, do not paste this over it. Hook events are siblings inside one hooks object, so the safe edit is a merge. This command backs up the file, appends the three entries to whatever is already there, validates the result with jq, and replaces the original only if it is valid JSON. Run it once, since a second run adds duplicate entries:
cp ~/.claude/settings.json ~/.claude/settings.json.bak
jq --arg cmd "$HOME/bin/route-agent-event.sh claude" '
.hooks //= {}
| .hooks.Notification = ((.hooks.Notification // []) + [{hooks: [{type: "command", command: $cmd}]}])
| .hooks.Stop = ((.hooks.Stop // []) + [{hooks: [{type: "command", command: $cmd}]}])
| .hooks.StopFailure = ((.hooks.StopFailure // []) + [{hooks: [{type: "command", command: $cmd}]}])
' ~/.claude/settings.json > ~/.claude/settings.json.new \
&& jq empty ~/.claude/settings.json.new \
&& mv ~/.claude/settings.json.new ~/.claude/settings.json
I ran that merge against a settings file holding a model, a permissions rule, an existing PostToolUse hook, and an existing Notification hook. All four survived, and Notification ended up with both entries. Then type /hooks in Claude Code and confirm the hooks appear under Notification, Stop, and StopFailure. Keep these hooks in your user settings, not in a repository's .claude/settings.json, so that no checked-in file decides where your alerts go.
Codex CLI: notify, hooks and TUI notifications
Codex has three separate mechanisms, and they cover different events. Verified against the Codex configuration docs, the Codex hooks docs, and the openai/codex repository on October 30, 2026:
- notify is a top-level array in ~/.codex/config.toml. Codex runs that program and passes one JSON argument, appended as the last argument. The docs say it currently receives only agent-turn-complete, with fields type, thread-id, turn-id, cwd, input-messages, and last-assistant-message. Codex ignores notify in a project-local .codex/config.toml and prints a startup warning, so set it in the user-level file.
- tui.notifications is a boolean or a list of event types, and the docs give agent-turn-complete and approval-requested as examples. tui.notification_method takes auto, osc9, or bel, and tui.notification_condition takes unfocused (the default) or always. For a terminal ding when Codex wants an approval, set the method to bel.
- Hooks are enabled by default. A PermissionRequest hook runs when Codex is about to ask for approval, such as a shell escalation or a managed-network request, and it does not run for commands that need no approval. A Stop hook runs at the end of a turn. Hooks you wrote yourself must be reviewed and trusted through /hooks before they run, a changed hook is skipped until you trust it again, and project-local hooks load only in trusted projects.
# ~/.codex/config.toml (root keys first, tables after)
notify = ["/home/you/bin/route-agent-event.sh", "codex"]
[tui]
notifications = ["agent-turn-complete", "approval-requested"]
notification_method = "bel"
notification_condition = "always"
For an external alert on approvals, add a hook file. Stop expects JSON on stdout when it exits 0 and treats plain text as invalid, so a notifier should print nothing, as the script below does. Exit 0 with no output counts as success, and for PermissionRequest it leaves the normal approval prompt in place:
{
"hooks": {
"PermissionRequest": [{ "hooks": [{ "type": "command", "command": "/home/you/bin/route-agent-event.sh codex" }] }]
}
}
If you prefer hooks for completion too, register the same script under Stop in this file and remove the notify line, or you will get two alerts per turn. Issue 19921 in the openai/codex repository asks for plan-mode-prompt and approval-requested to reach the top-level notify program. It was still open on October 30, 2026, and an OpenAI maintainer replied on April 28, 2026 that notify will soon be deprecated in favor of hooks, so extending it is unlikely. Treat hooks as the path for approvals and keep notify only for completion.
One routing script for both CLIs
Alert logic goes in one script that classifies the event, picks a priority, and posts a fixed message. It reads two environment variables, ALERT_URL (required) and ALERT_TOKEN (optional bearer token), and needs bash, jq, and curl. The first argument names the tool. Claude Code and the Codex hooks send JSON on stdin, and Codex notify passes it as the last argument.
#!/usr/bin/env bash
# Usage: route-agent-event.sh claude|codex [json] (payload on stdin, or as the last argument)
# Needs: bash, jq, curl. Environment: ALERT_URL (required), ALERT_TOKEN (optional bearer token).
set -eo pipefail
tool="$1"
[ -n "$tool" ] && [ -n "$ALERT_URL" ] || { echo "usage: tool name and ALERT_URL required" >&2; exit 0; }
if [ "$#" -ge 2 ]; then
for payload; do :; done # Codex notify appends its JSON as the last argument
else
payload="$(cat)" # Claude Code and Codex hooks send JSON on stdin
fi
# Classify from allowlisted fields only. No payload text is ever copied into the alert.
kind="$(printf '%s' "$payload" | jq -r '
def safe: (type == "string") and test("^[a-z_]{1,40}$");
if .type == "agent-turn-complete" then "done"
elif .hook_event_name == "Stop" then "done"
elif .hook_event_name == "StopFailure" then (if (.error | safe) then "error:" + .error else "error:unknown" end)
elif .hook_event_name == "PermissionRequest" then "input"
elif .hook_event_name == "Notification" then
(if (.notification_type | IN("permission_prompt","elicitation_dialog","elicitation_url_dialog","agent_needs_input")) then "input"
elif .notification_type == "idle_prompt" then "idle"
elif .notification_type == "agent_completed" then "done"
else "ignore" end)
else "ignore" end' 2>/dev/null)" || { echo "unparseable payload" >&2; exit 0; }
case "$kind" in
input) title="$tool needs you"; prio=high ;;
idle) title="$tool is waiting"; prio=default ;;
done) title="$tool finished a turn"; prio=default ;;
error:*) title="$tool turn failed ($(printf '%s' "$kind" | cut -d: -f2))"; prio=high ;;
*) exit 0 ;;
esac
set -- -fsS --max-time 10 -o /dev/null -H "Title: $title" -H "Priority: $prio"
[ -z "$ALERT_TOKEN" ] || set -- "$@" -H "Authorization: Bearer $ALERT_TOKEN"
curl "$@" -d "Open the session to see details." "$ALERT_URL" || echo "alert delivery failed" >&2
exit 0
The script never copies payload text into the alert. It reads only hook_event_name, notification_type, type, and an error value that must match a short lowercase pattern, and the message body is a constant. That design is the security section in practice.
Test the routing before trusting it
Save this next to the script with the small mock below. It sends nine payloads to a listener on 127.0.0.1: the permission prompt, idle prompt, Stop, StopFailure, and a Notification type the script should ignore, a Codex notify completion and a Codex PermissionRequest, and two hostile payloads with shell syntax in the message and in the error field. No CLI, no network, and no private data are involved.
import json, sys
from http.server import BaseHTTPRequestHandler, HTTPServer
log = sys.argv[2]
class H(BaseHTTPRequestHandler):
def do_POST(self):
body = self.rfile.read(int(self.headers.get("Content-Length", 0))).decode()
rec = {"path": self.path, "title": self.headers.get("Title"), "priority": self.headers.get("Priority"),
"auth": bool(self.headers.get("Authorization")), "body": body}
open(log, "a").write(json.dumps(rec) + "\n")
self.send_response(200); self.end_headers()
def log_message(self, *a): pass
HTTPServer(("127.0.0.1", int(sys.argv[1])), H).serve_forever()
#!/usr/bin/env bash
# Simulated routing check against a local mock. No CLI, no network, no private data.
export ALERT_URL=http://127.0.0.1:18765/agent-alerts ALERT_TOKEN=tk_fixture_not_a_real_token
python3 -I mock.py 18765 "$PWD/log.jsonl" & srv=$!; sleep 1
R=./route-agent-event.sh
echo '{"hook_event_name":"Notification","notification_type":"permission_prompt"}' | $R claude
echo '{"hook_event_name":"Notification","notification_type":"idle_prompt"}' | $R claude
echo '{"hook_event_name":"Stop","last_assistant_message":"done"}' | $R claude
echo '{"hook_event_name":"StopFailure","error":"rate_limit"}' | $R claude
echo '{"hook_event_name":"Notification","notification_type":"plugin_notification"}' | $R claude
$R codex '{"type":"agent-turn-complete","last-assistant-message":"ok"}'
echo '{"hook_event_name":"PermissionRequest","tool_name":"Bash"}' | $R codex
# Hostile text: must not execute and must not appear in any request
echo '{"hook_event_name":"Stop","last_assistant_message":"$(touch PWNED) sk-secret-123"}' | $R claude
echo '{"hook_event_name":"StopFailure","error":"x; touch PWNED #"}' | $R claude
kill $srv
test ! -e PWNED && echo "no injection marker"
grep -c 'sk-secret\|touch' log.jsonl
Simulated routing check (no CLI involved). I ran this on October 30, 2026 with bash 5, jq 1.7, and curl, after bash -n reported no syntax errors for the script and the fixture. Nine payloads produced eight requests: the plugin_notification payload was correctly ignored. Titles and priorities were "claude needs you" (high), "claude is waiting" (default), "claude finished a turn" (default, twice), "claude turn failed (rate_limit)" (high), "claude turn failed (unknown)" (high, the hostile error value), "codex finished a turn" (default), and "codex needs you" (high). The injection marker file was never created, no request body contained the hostile text, and the token travelled in the Authorization header on every request.
Real CLI experiments (separate from the check above). I ran a one-line capture hook (shown in the next section) against real binaries with a trivial prompt in an empty directory. Claude Code 2.1.312 in print mode delivered a Stop payload on stdin with hook_event_name, last_assistant_message, stop_hook_active, background_tasks, session_crons, and a few session fields. No Notification event arrived in that single non-interactive turn. Codex CLI 0.166.0 in exec mode ran the notify program once with a JSON argument whose keys were type (agent-turn-complete), client, thread-id, turn-id, cwd, input-messages, and last-assistant-message. With this guide's script registered, a real Claude Code Stop hook and a real Codex notify each produced one request to the local mock. I did not test permission prompts, StopFailure, or approvals on a real CLI, and I did not test delivery to a physical phone, so those rows are simulated only.
Troubleshooting sequence
When an alert does not arrive, walk the chain from the CLI outward and stop at the first step that fails.
- Was the event emitted? Register this capture script for the same event and trigger it. A file in ~/hook-capture means the CLI emitted the event and you can read its exact fields. Remember that Claude's Notification types for permission and idle only fire after the delays in the table, and only when you appear to be away.
#!/usr/bin/env bash # Writes whatever the CLI sends (stdin, or the last argument for Codex notify) to a file. mkdir -p "$HOME/hook-capture" if [ "$#" -ge 1 ]; then for p; do :; done; printf '%s' "$p" > "$HOME/hook-capture/$(date +%s%N).json" else cat > "$HOME/hook-capture/$(date +%s%N).json"; fi - Is the hook registered? In Claude Code, /hooks lists the hook under its event, and a settings edit that does not show up after a few seconds needs a session restart. In Codex, /hooks shows whether a hook is waiting for your trust. Matchers are case-sensitive.
- Was the command invoked? Pipe a sample payload into the script by hand, such as
echo '{"hook_event_name":"Stop"}' | ./route-agent-event.sh claude, and check the exit code. Use absolute paths, make the script executable, and install jq. On a server, a hook that calls notify-send fails silently because there is no desktop notification daemon. - Can the destination be reached? From the same machine and user, run the curl by hand with the token and read the HTTP status. A headless box needs outbound HTTPS to your push server, and the token must be in the environment of the process that launches the CLI.
- Is the device subscribed and authorized? The phone app must subscribe to the same topic, the account behind it needs read access, and the OS must allow notifications for the app. On iOS, Focus modes and notification summaries can hold alerts back.
Sending alerts to a phone, with limits
The router above posts to any URL that accepts a POST with Title and Priority headers, which is how ntfy works. ntfy is an open-source publish and subscribe service with Android and iOS apps and a server you can host yourself. Its publishing docs state that on the public server a topic created by publishing is "essentially a password", so a long random topic name reduces guessing. A topic name is still not access control: it sits in client configuration and shell history, and anyone who learns it can read and publish. For anything you would not post publicly, use a server with access control, where ntfy lets you set auth-default-access to deny-all, create users, and issue access tokens, and where tokens go in an Authorization: Bearer header over HTTPS.
Claude Code also has its own phone path. With Remote Control active, /config offers "Push when Claude decides" and "Push when actions required", delivered to the Claude mobile app. Anthropic's documentation says Claude decides when to push and that there is no per-event configuration beyond those two switches. For starting and steering sessions from a phone, see how to run Claude Code from your phone.
Security: what an alert hook can leak or run
Two things can go wrong. The first is exposure: a hook payload carries the session's transcript path and working directory, and Stop and StopFailure add the model's last message, which can contain code, file contents, or secrets the agent read. Codex notify adds your input messages. Anything you forward goes to the push server's operator and to every device subscribed to the topic. The second is execution: a hook is a shell command with your user's privileges, and the text in a payload is influenced by whatever the agent read, including web pages and repository files that may contain hostile instructions.
The trust boundary sits at the script. It trusts the local user account, the CLI's choice of event name, and the TLS connection to your push server. It does not trust payload text. The rules the script follows:
- Send generic, allowlisted text only. The title comes from a fixed set, the body is constant, and the one variable value, the error type, must match
^[a-z_]{1,40}$or becomes "unknown". - Never put payload text into a shell string. A command such as
sh -c "notify '$msg'"executes whatever the message contains. Pass data as separate arguments or through jq, and quote every expansion. - Keep the token and URL in the environment, set in the shell profile or a service unit, not in the settings file or on the hook's command line, where
psand a committed config can expose them. See keeping secrets out of agent prompts for the wider habit. - Keep alert configuration at user level. Codex already ignores notify in project config and gates project hooks on trust, and the same discipline applies to Claude Code settings.
Limits: generic text hides the content, but the destination still learns that a session needs you and when. Self-hosting removes a third party, not the risk to your own server. And if an attacker can write your user-level settings or the script, the script cannot protect you. Three checks you can run today:
- Run the fixture's two hostile payloads and confirm no PWNED file appears and
grep -c 'sk-secret\|touch' log.jsonlprints 0. - Search your configuration for the token:
grep -rc tk_ ~/.claude/settings.json ~/.codex/config.tomlshould report 0 for both. - Publish without credentials to your private server and confirm it is refused:
The status should be a 4xx. A 200 means the topic is open to anyone who knows its name.curl -s -o /dev/null -w "%{http_code}\n" -d "test" https://ntfy.example.com/agent-alerts
For the underlying hook model and its permission risks, see coding agent hooks explained and coding agent permission modes.
Where notifications stop helping
Alerts work well for one person with a session or two on one machine. Two limits show up beyond that. A session on a laptop stops when the laptop sleeps or the network drops, which is the problem in keeping Claude Code running after you close the laptop. And an alert reaches the person who started the session, which may not be the person with time to look. With many sessions the alert also stops saying which one needs you, which monitoring multiple coding agent sessions covers. When the same developer who prompted the agent also reviews its output, review turns into self-review.
Where AQ fits
AQ is the multiplayer coding harness where teams build and run bots with every AI coding agent, like Claude Code and Codex: shared live terminals, review and merge, app previews and standing jobs, in your own cloud. Three separate things are easy to blur here, so this section keeps them apart.
- Mobile access. AQ works in any phone browser. Home, Work, Genie, and You are the four tabs, and every thread opens with its transcript, answer dock, preview, and terminal. You can answer questions, approvals, and plan gates from the Needs you cards. See AQ on your phone.
- Built-in notifications. The iPhone app is in beta. AQ's documentation says it adds push notifications for every AQ notification, with agent questions arriving as time-sensitive, and one Live Activity for all your running work.
- Hooks you configure in a CLI. AQ's documentation does not describe forwarding a Claude Code hook or a Codex notify payload into the iPhone app's push. This guide does not claim it, and the hooks above remain the CLI's own feature.
AQ runs agent CLIs in persistent sessions on a machine in your own cloud, and teammates can open the same workspace from a link. That speaks to the two limits above: a session that outlives a closed laptop, and a place where someone other than the person who started it can see what is waiting. On pricing, AQ has two plans. Free is $0 and runs agents on your own Mac with the AQ Mac app, while your Mac is awake. Pro is $50 per user per month in early access (the standard price is $200), billed monthly, with the rate locked for your first 12 months. Details are on the pricing page.
If you run one or two sessions on your own machine, the hooks and script in this guide are enough.
Frequently asked questions
How do I get notified when Claude Code finishes or needs me?
Use three hooks in ~/.claude/settings.json: Notification for approvals and questions, Stop for a finished turn, and StopFailure for a turn that ended on an API error. For a sound only, set preferredNotifChannel to terminal_bell. Claude Code sends desktop notifications by default only in iTerm2, Ghostty, and Kitty, and the permission_prompt notification fires after about six seconds without typing in a terminal session. A finished turn is not proof the work succeeded, so make the alert say to open the session.
Why does my agent_completed hook never fire?
agent_completed is a Notification type for background sessions, and it fires only while agent view is open in a terminal. An ordinary foreground session does not emit it. Use the Stop hook to detect a finished turn, and check background_tasks in its payload to tell a finished session from one paused for background work.
What is the difference between Notification, Stop, and StopFailure?
Notification fires when Claude needs approval or input (permission_prompt, elicitation dialogs) or has been idle for about 60 seconds (idle_prompt). Stop fires when the main agent finishes responding and does not run on a user interrupt. StopFailure fires instead of Stop when the turn ends on an API error such as rate_limit or authentication_failed. Notification and StopFailure output and exit codes are ignored, so test the command by hand.
Can Codex alert me when it needs approval or finishes?
Yes, with limits. The tui.notifications setting accepts event types such as agent-turn-complete and approval-requested, and tui.notification_method can be set to bel for a terminal bell. The external notify program receives only agent-turn-complete according to the Codex docs. For an external alert on approvals, register a PermissionRequest hook, which runs when Codex is about to ask for approval. openai/codex issue 19921, which asks for approvals in notify, was still open on October 30, 2026, and a maintainer said notify will soon be deprecated in favor of hooks.
Why do notifications fail on a server or over SSH?
The usual causes are a missing desktop notification daemon (notify-send fails silently on headless machines), tmux without set -g allow-passthrough on, an iTerm2 profile without escape-sequence alerts enabled, or a server with no outbound access to your push service. Work through the chain: was the event emitted, is the hook registered, was the command invoked, can the destination be reached, and is the phone subscribed and allowed to notify.
Is it safe to send agent notifications to a push service like ntfy?
It is safe only when the message carries nothing sensitive. Hook payloads include the working directory and the model's last message, which can hold code or secrets, so send fixed text such as "needs you" and a priority. Never interpolate payload text into a shell command, keep the token in an environment variable, and use a server with access control for private use. ntfy's own documentation describes an unreserved topic as essentially a password, which is a weak secret rather than access control.