Hooks / notifications

Notify when Claude needs input

Desktop notification when Claude asks for permission or goes idle waiting for you.

What it does

Fires on Notification with the permission_prompt, idle_prompt, and agent_needs_input matchers, then posts a native desktop notification (osascript on macOS, notify-send on Linux). Runs detached so notification daemons never stall the session. Note: agent_needs_input is one of the newer matcher values - older Claude Code versions simply will not fire it.

When it runs

Config

Merge this into .claude/settings.json (or ~/.claude/settings.json for user scope) - or use the generator to combine hooks.

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/notify-input-needed.sh",
            "timeout": 10,
            "async": true
          }
        ],
        "matcher": "permission_prompt|idle_prompt|agent_needs_input"
      }
    ]
  }
}

Script

Save as .claude/hooks/notify-input-needed.sh and chmod +x it.

#!/bin/bash
# notify-input-needed: desktop notification on permission/idle prompts.
set -u
msg="Claude needs your input"
if command -v osascript >/dev/null 2>&1; then
  osascript -e "display notification \"$msg\" with title \"Claude Code\"" >/dev/null 2>&1 &
elif command -v notify-send >/dev/null 2>&1; then
  notify-send "Claude Code" "$msg" >/dev/null 2>&1 &
fi
exit 0

Install

1. Save the script to .claude/hooks/notify-input-needed.sh and chmod +x it.
2. Add the config fragment to ~/.claude/settings.json (user scope - useful in every project).

Test it

• Positive: trigger a permission prompt (e.g. a command that needs approval) - a desktop notification should appear.
• Negative: normal tool calls that need no approval should not notify.

Sources

• Claude Code hooks reference (checked 2026-09-10)

Related hooks