Get Notified the Moment Claude Code Is Waiting for Your Input

The most expensive state in a Claude Code session isn't "working." It's "waiting." Claude hits a permission prompt — may I run this command, may I edit this file — and stops. Or it finishes a thought and sits idle, cursor blinking, while you're in another window assuming it's still busy. Ten minutes later you tab back to discover your agent has been politely waiting for a single keypress the whole time.

Most notification guides focus on the moment Claude Code finishes. This one is about the moment it needs you — which happens more often, matters more, and uses a different hook than most people configure.

Stop fires when it's done. Notification fires when it's stuck.

Claude Code's hook system has two events that people constantly mix up. The Stop hook fires when Claude finishes responding — the "task complete" moment. The Notification hook fires when Claude Code is trying to get your attention mid-task: it needs permission to use a tool, or it has been sitting idle waiting for your input.

If you've only wired up Stop, you get an alert when the work ends — but total silence at exactly the moment work is blocked. That's how a "two-minute task" quietly becomes a twenty-minute one: the agent asked a question at minute one and nobody heard it.

The setup: a Notification hook that makes noise

Add this to your ~/.claude/settings.json (or a project's .claude/settings.json). On macOS it plays a sound and shows a banner whenever Claude Code is waiting on you:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff; osascript -e 'display notification \"Claude Code needs your input\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

A hook entry without a matcher runs for every Notification event — permission requests and idle waits alike. That's the right default: when you're starting out, you want to hear about both. On Linux, swap the command for notify-send "Claude Code" "Needs your input" plus your sound player of choice; more variations (including Windows) live in our copy-paste notification scripts collection.

Permission prompts vs. idle waits

Under the hood, Notification events come in flavors — the two that matter day-to-day are the permission prompt (Claude wants to run a tool and your settings require approval) and the idle prompt, which fires after Claude has been waiting for your input for around a minute. If you find the idle alerts too chatty — they can lag the actual moment Claude went quiet — you can use a matcher to keep only the permission alerts, which are always urgent:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Sosumi.aiff"
          }
        ]
      }
    ]
  }
}

A good mental model: permission prompts deserve an interruption — the agent literally cannot proceed. Idle waits deserve a gentle nudge — useful, but occasionally late or redundant. Tune the two separately and the setup stops feeling noisy.

Pair it with Stop for full coverage

The complete picture is three moments: needs permission, waiting on input, finished. The first two are the Notification hook; the last one is Stop. Our full Claude Code notifications guide walks through the whole matrix, including the terminal bell option and pushing alerts to your phone. If you run several sessions at once, notifications stop being a luxury entirely — see running multiple Claude Code sessions without losing track.

When you'd rather not maintain hook configs

Hooks are powerful, but they're also JSON you have to write, debug, and copy to every machine — and they only cover Claude Code. If you also run Codex or Cursor, each tool has its own completely different mechanism for the same "needs input" moment.

Either way, the goal is the same: an agent that can summon you the moment it's blocked. Configure the Notification hook once — or install something that listens for you — and the waiting tax disappears from every session after that.