The Claude Code Notification hook
Updated
Quick answer
The Notification hook runs when Claude Code wants your attention. Its notification_type says why: permission_prompt when a permission prompt has waited about six seconds, idle_prompt about a minute after Claude finished if you have not typed, and others for sign-in and MCP dialogs. It can alert you, but it cannot answer the prompt: for that, use PermissionRequest.
When it fires
Claude Code runs the hook each time it sends a notification, and passes the reason in notification_type. The matcher filters on that value. The ones that mean someone should look:
Swipe the table sideways to see both columns.
| Type | Fires when |
|---|---|
permission_prompt | Claude needs your approval for a tool, or for a sandboxed command’s network request, and the prompt has waited about six seconds |
idle_prompt | Claude finished responding about 60 seconds ago and you haven’t typed since |
elicitation_dialog | An MCP server opened a form and you haven’t typed for about six seconds |
elicitation_url_dialog | An MCP server asks you to open a link, with the same six-second wait |
agent_needs_input | A background session waits for you while agent view is open |
Others are informational: auth_success after a sign-in, agent_completed when a background session ends while agent view is open, and the quota_auto_resume_* types around a usage limit. The hook runs even if you turned Claude Code’s own notifications off: preferredNotifChannel changes how Claude Code alerts you, not whether your hook runs.
What it receives
Standard input
{
"session_id": "abc123",
"cwd": "/Users/you/dev/harbor",
"hook_event_name": "Notification",
"message": "Claude needs your permission",
"notification_type": "permission_prompt"
}
A title can come too. That is all: no tool name, no command. The hook can’t block or change the notification, and Claude Code discards systemMessage and continue from its output. It still emits a terminalSequence you return, which is how a hook can raise a desktop notification in terminals that read one. The hook is made for side effects: show an alert, play a sound, forward the moment to another service.
Keep only the types that mean “come back”
An empty matcher fires on every type, sign-ins included. List the ones you want, separated by |:
~/.claude/settings.json
{
"hooks": {
"Notification": [
{
"matcher": "permission_prompt|elicitation_dialog|elicitation_url_dialog",
"hooks": [{ "type": "command", "command": "~/.claude/hooks/come-back.sh" }]
}
]
}
}
~/.claude/hooks/come-back.sh (macOS, needs jq)
#!/bin/sh
# Notification hook: say which project needs you, and why.
input=$(cat)
project=$(basename "$(printf '%s' "$input" | jq -r '.cwd')")
msg=$(printf '%s' "$input" | jq -r '.message // "Claude needs you"')
osascript -e 'on run argv' -e 'display notification (item 2 of argv) with title (item 1 of argv)' \
-e 'end run' "Claude Code · $project" "$msg"
exit 0
Only the osascript line depends on the system:
Swipe the table sideways to see both columns.
| System | Alert line |
|---|---|
| macOS | osascript, as above, or terminal-notifier |
| Linux desktop | notify-send "Claude Code · $project" "$msg" |
| Windows | New-BurntToastNotification -Text 'Claude Code', $msg, in a hook with "shell": "powershell" |
A terminal that shows notifications from escape sequences needs no system command at all: OSC 777 for Ghostty and Warp, OSC 9 for iTerm2, OSC 99 for Kitty. The hook returns the sequence in terminalSequence, and Claude Code writes it to the terminal for you, since a hook has no terminal of its own:
OSC 777, read by Ghostty and Warp
#!/bin/sh
input=$(cat)
body=$(printf '%s' "$input" | jq -r '.message // "Needs your attention"')
seq=$(printf '\033]777;notify;%s;%s\007' "Claude Code" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'
Add idle_prompt to the matcher if you also want a nudge a minute after Claude finishes, or use a Stop hook to know the moment it does.
Why it seems slow
The six seconds are deliberate. In a terminal session, these types share their timing with Claude Code’s own desktop notifications, which are meant for when you appear to be away. The timer starts when the prompt appears, and each keystroke defers it. idle_prompt waits about 60 seconds, and doesn’t fire while a background subagent is still running or while Claude Code waits for a usage limit to reset.
In the VS Code extension and the desktop app, which handle permission requests through the Agent SDK, permission_prompt fires about six seconds after the request and typing doesn’t defer it; if you or a PermissionRequest hook answer sooner, it doesn’t fire at all. Before version 2.1.233, it didn’t fire in those hosts. Setting CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS=1 turns it off there.
Notification, Stop or PermissionRequest
| You want | Use |
|---|---|
| An alert the moment Claude finishes a turn | Stop |
| An alert the moment a permission is asked | PermissionRequest, printing nothing so the prompt still shows |
| To answer the permission prompt from elsewhere | PermissionRequest, returning allow or deny |
| To know about a form, a link to open, or a sandboxed network request | Notification |
| A nudge if you never came back after Claude finished | Notification with idle_prompt |
One case only Notification covers: a sandboxed command’s network request doesn’t go through PermissionRequest, so permission_prompt is the only signal for it. For the moments it answers, Monish uses PermissionRequest and Stop, which don’t wait the six seconds.
Questions
- Can the Notification hook answer the permission prompt?
- No. It can’t block or change anything. Use a PermissionRequest hook to return allow or deny.
- Why doesn’t my hook fire while I’m typing?
- In a terminal session, each keystroke defers permission_prompt, and idle_prompt only fires if you haven’t typed since Claude finished. Both are meant for when you are away.
- Does turning off Claude Code’s notifications stop my hook?
- No. The preferredNotifChannel setting, notifications_disabled included, changes how Claude Code alerts you, not whether your Notification hook runs.
- Why didn’t permission_prompt fire in the VS Code extension?
- Before Claude Code 2.1.233 it didn’t fire in sessions hosted through the Agent SDK, such as the VS Code extension and the desktop app. Update Claude Code; there it fires about six seconds after the request.
More guides
- The Claude Code Stop hookRun a command when Claude finishes, or send it back to work without a loop.
- The Claude Code PermissionRequest hookAnswer a permission prompt from a script: input, output, limits.
- Get notified when Claude Code finishesThe Stop hook on macOS, Windows and Linux, then on your phone.
- Claude Code notifications not working: five causesIs the hook loaded, does it run, is it the right event.
New to Monish? The home page shows what lands on your iPhone, and all guides are listed here.
Get Monish on your iPhone
Free, no account. Your 6-digit code is waiting in the app.