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.

TypeFires when
permission_promptClaude needs your approval for a tool, or for a sandboxed command’s network request, and the prompt has waited about six seconds
idle_promptClaude finished responding about 60 seconds ago and you haven’t typed since
elicitation_dialogAn MCP server opened a form and you haven’t typed for about six seconds
elicitation_url_dialogAn MCP server asks you to open a link, with the same six-second wait
agent_needs_inputA 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.

SystemAlert line
macOSosascript, as above, or terminal-notifier
Linux desktopnotify-send "Claude Code · $project" "$msg"
WindowsNew-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 wantUse
An alert the moment Claude finishes a turnStop
An alert the moment a permission is askedPermissionRequest, printing nothing so the prompt still shows
To answer the permission prompt from elsewherePermissionRequest, returning allow or deny
To know about a form, a link to open, or a sandboxed network requestNotification
A nudge if you never came back after Claude finishedNotification 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

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.

Download on the App Store