How to get notified when Claude Code needs your input or approval.

(1)Step 1 · Built-in

Start with the alert Claude Code already sends.

When a permission prompt is waiting or Claude has finished, and you appear to be away from the terminal, Claude Code raises a notification. In Ghostty, Kitty and iTerm2 it becomes a desktop notification with no setup. In other terminals, such as Warp or the VS Code integrated terminal, set preferredNotifChannel to "terminal_bell" to ring the bell instead. The same setting appears in /config as Local notifications.

The built-in notification also reaches your laptop when Claude Code runs over SSH, which a plain hook command cannot do, because hooks run on the remote machine. Ghostty and Kitty forward it with no setup. iTerm2 needs forwarding turned on: Settings → Profiles → Terminal, check Notification Center Alerts, then Filter Alerts and enable Send escape sequence-generated alerts.

{
  "preferredNotifChannel": "terminal_bell"
}

(2)Step 2 · Notification hook

Get a banner that says which project is asking, and for what.

A Notification hook runs your own command when Claude Code sends a notification, and it still runs if you set preferredNotifChannel to notifications_disabled. Its JSON input includes message (the notification text), notification_type, and cwd, the session’s working directory. The script below turns the folder name into the banner title, so “payments-api: approval needed” and “docs: waiting for you” look different at a glance.

Save it as ~/.claude/hooks/notify.sh, make it executable with chmod +x, and register it for the four types that mean Claude is blocked on you. It needs jq (brew install jq if it is missing). The on run argv form hands the text to osascript as arguments, so quotes inside a message or command cannot break the AppleScript.

#!/bin/bash
# Claude Code hook: say which project is asking, and for what.
input=$(cat)
project=$(basename "$(jq -r '.cwd // "Claude Code"' <<<"$input")")

case "$(jq -r '.notification_type // .hook_event_name' <<<"$input")" in
  permission_prompt|PermissionRequest) title="$project: approval needed" ;;
  idle_prompt) title="$project: waiting for you" ;;
  PreToolUse) title="$project: Claude has a question" ;;
  *) title="$project: Claude Code" ;;
esac

body=$(jq -r '.message // .tool_input.command // .tool_input.file_path // .tool_input.questions[0].question // .tool_name // "Needs your attention"' <<<"$input" | head -c 180)

osascript -e 'on run argv' -e 'display notification (item 2 of argv) with title (item 1 of argv)' -e 'end run' "$title" "$body" >/dev/null 2>&1
exit 0

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt|elicitation_dialog|elicitation_url_dialog",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/notify.sh" }
        ]
      }
    ]
  }
}

(3)Step 3 · Instant alerts

Get the alert the moment Claude asks, not six seconds later.

permission_prompt waits until you have not typed for about six seconds, and every keystroke pushes it back. That keeps it quiet while you are at the keyboard, but it can feel late. PermissionRequest runs as soon as Claude is about to ask, and a PreToolUse hook matched to AskUserQuestion runs before Claude shows you a multiple-choice question. Point both at the same script: it reads tool_input and puts the command, file path or question in the banner.

The cost is noise: these fire even while you are looking straight at the prompt. Use them in place of the permission_prompt matcher, not alongside it, or an approval you miss will alert you twice. Keep permission_prompt if you use the sandbox, because PermissionRequest does not fire for a sandboxed command’s network request.

{
  "hooks": {
    "PermissionRequest": [
      {
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/notify.sh", "async": true }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "AskUserQuestion",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/notify.sh", "async": true }
        ]
      }
    ]
  }
}

(4)Step 4 · Linux and Windows

The same hooks on Linux and Windows.

On Linux, keep the script and swap its osascript line for notify-send, which ships in libnotify-bin on Debian and Ubuntu. It needs a running notification daemon, so it will not show anything in an SSH session, on a headless server or in most containers.

On Windows, the hooks guide uses a PowerShell message box. It is a dialog, not a corner toast, so it can open behind your terminal. Inside WSL, powershell.exe must be on your PATH through Windows interop. The JSON shape is the same on every platform; only the command changes.

notify-send "$title" "$body"

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

(5)Away from the desk

Answer from your phone, not just notice.

A banner on your Mac does nothing while you are in the kitchen. Remote Control connects a local session to the Claude app on iOS or Android and to claude.ai/code. Start the session with claude --remote-control, then in /config turn on Push when actions required, which covers permission prompts and questions. Permission prompts stay open until you answer, from the terminal or the phone. Remote Control needs a claude.ai login on a Pro, Max, Team or Enterprise plan (on Team and Enterprise an Owner turns it on first), and it is not available with API keys, Amazon Bedrock, Google Cloud’s Agent Platform or Microsoft Foundry.

If Remote Control is not an option, claude-remote-approver installs a PermissionRequest hook that sends each prompt to the ntfy app with Approve, Always Approve and Deny buttons, and falls back to the terminal prompt if you do not answer in time. On the public ntfy.sh server, tool names and commands pass through a third party, so its README suggests self-hosting ntfy for sensitive work. Either way, read the command before you tap Approve.

cd ~/code/payments-api
claude --remote-control

(6)Out loud

Hear the question instead of reading a banner.

A banner only helps if you look at the screen. On macOS, pipe the notification text into say and your Mac reads it aloud with the project name first, which works while your eyes are on another window or you are across the room. On Linux, spd-say does the same. It reads the text exactly as written, which is fine for a short notification.

Heard is a voice layer for coding agents on macOS 14 or later. Its native Claude Code and Codex adapters speak questions, approvals, blockers, failures and results, and name the session each one came from, so with four sessions open you hear which one needs you and why. On Heard Power you can dictate a reply and send it to that session without switching windows, from the Mac or a paired iPhone. The app installs its own hook; see the Claude Code setup docs. New accounts start with a 14-day Power trial, no card required, and the engine is open source under Apache 2.0.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [
          {
            "type": "command",
            "async": true,
            "command": "jq -r '(.cwd | split(\"/\") | last) + \". \" + (.message // \"Claude Code needs you\")' | say"
          }
        ]
      }
    ]
  }
}

(7)Fewer interruptions

Only get interrupted when a decision is waiting.

Every alert should mean you have something to decide. These rules keep it that way.

• Match permission_prompt|idle_prompt|elicitation_dialog|elicitation_url_dialog instead of leaving the matcher empty. An empty matcher also fires on auth_success, elicitation_complete and the usage-limit types.
• Give “done” its own sound with a Stop hook (setup) so “finished” and “needs you” never sound alike.
• Cut the prompts themselves. Add an allow rule such as Bash(npm test *) in /permissions for commands you always approve, and that prompt, and its alert, goes away.
• Using agent view for background sessions? Add agent_needs_input to the matcher.
• With Remote Control, set CLAUDE_CLIENT_PRESENCE_FILE to a marker file that a screen-lock tool removes when you lock the screen and recreates when you are back. Phone pushes are skipped while the file exists.
• Running several sessions with Heard? Its Focus mode stays quiet until an agent needs you: questions, approvals, blockers and failures.

(8)Troubleshooting

If the alert never comes, or comes late.

Most missing alerts come down to one of these.

• No banner from osascript: it posts through Script Editor and fails silently without permission. Run osascript -e 'display notification "test"' once, then turn on Allow Notifications for Script Editor in System Settings → Notifications.
• Banners vanish during a macOS Focus: add Script Editor, or your terminal for the built-in notification, to the apps that Focus allows.
• The alert is late: that is the six-second rule for permission_prompt, which restarts on every keystroke, or the 60-second wait for idle_prompt. Use PermissionRequest for an immediate alert.
• No idle_prompt at all: it does not fire while a background subagent is still running, or while Claude Code waits for a usage limit to reset.
• The hook is missing: run /hooks. Edits are normally picked up on their own; if the hook still does not appear, restart the session and check the JSON for trailing commas.
• Over SSH, osascript and notify-send run on the server. Use the built-in notification in Ghostty, Kitty or iTerm2, or have the hook return a terminalSequence so Claude Code sends the notification through your terminal.
• Inside tmux, the built-in notification needs set -g allow-passthrough on in ~/.tmux.conf, then tmux source-file ~/.tmux.conf.
• In Claude Desktop or the VS Code extension, permission_prompt arrives about six seconds after the request even while you type. Set CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS=1 to turn it off there.
• Remote Control pushes not arriving: if /config shows No mobile registered, open the Claude app once. On iOS, check that a Focus or notification summary is not holding Claude’s notifications.