Claude Code notifications: the Stop and Notification hooks

Claude Code ships two hooks that need no extra tooling: Stop, which fires when Claude finishes responding, and Notification, which fires when it is waiting on you — a permission prompt, an idle prompt, an MCP server asking for input. Wire either to a shell command in settings.json and you get a sound, a desktop banner, or anything else a command line can trigger. The config below is real and copy-pasteable. The honest part comes after: none of it reaches you once you've left the desk.

Where the hooks live#

Claude Code reads hooks from settings.json at one of three scopes: ~/.claude/settings.json (every project, this machine), .claude/settings.json (this project, checked into git, shared with the team), or .claude/settings.local.json (this project, not checked in — the right place for a personal afplay command your teammates don't need to see in a diff).

Each entry matches an event name to a list of matchers, and each matcher runs one or more shell commands — the shape is documented in Anthropic's own hooks reference, which is the authority on the full event list if you want more than the two below:

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

"matcher": "" matches every event of that type, which is what you want for Stop and Notification — matchers earn their keep on the tool-scoped hooks like PreToolUse, where you might only want to fire on Bash or Write.

On Linux, swap the commands for their equivalents:

notify-send "Claude Code" "Finished responding"

Stop is not the same signal as Notification#

The distinction is easy to gloss over and it is the one that determines what you wire to each hook.

Stop fires once, when Claude has finished producing a response and handed control back to you. That covers success, a completed refactor, an answered question, and Claude giving up and explaining why — Claude Code does not distinguish those cases through the Stop event alone. It means "come look," not "it worked."

Notification fires on the events that need you now: a tool-permission request, a plan-mode exit, an idle timeout waiting on input. Nothing else happens in that pane until you respond. If you only wire one hook, wire Notification — a Claude Code session that's blocked can sit for hours doing nothing, and a Stop hook will never fire to tell you that.

The same goes for Notification. A banner reading "Claude Code needs input" costs you exactly the context switch it was supposed to save; one carrying the command that's sitting at a y/n lets you decide from a lock screen whether it can wait until you're back.

The escalation path, and where it stops working#

That last row is deliberately not a notification, and it's the half the others leave out. Every tier above it answers "something happened"; none of them answer the question you actually have once the banner lands, which is what the pane currently says. mtmux covers that: it serves the tmux session Claude Code is already running in to a browser, end-to-end encrypted, with nothing to port-forward — so the follow-up to a push is opening the session, not finding a laptop. The reference setup for that pairing is at docs.mtmux.com/claude-code-remote.

If the agent is running inside tmux, there is a second, entirely separate place to hang the same shell command: tmux's own set-hook, which fires on what the pane does rather than on what Claude Code reports about itself — set-hook and capture-pane are both in tmux commands. It is a different tool with different blind spots, not a replacement for the hooks above.

What a good escalation setup actually looks like#

Bell for anything under a minute — you're probably still watching. Desktop notification for anything you'd otherwise poll for by tabbing back every thirty seconds. Push for anything you'd walk away from: a long refactor, a test suite you don't want to babysit, a migration you kicked off before lunch. If you're setting up hooks and stopping at desktop notifications, you've solved the "I forgot to check" problem and left the "I wasn't at my desk" problem untouched — which for long agent runs is the more common one. That's the argument made at length in stop babysitting coding agents.

If you also run OpenAI's CLI, the equivalent hook is different in shape and in what it goes silent on — see Codex CLI notifications. For the same question asked across every agent at once — which ones signal natively, and what each one stays quiet about — coding agent notifications is the survey this post is one chapter of.

The command inside the hook is a separate problem from the hook itself, and the one people get wrong: a banner you cannot hear is not much use in another room. Making Claude Code play a sound when it's done covers afplay, paplay and the PowerShell equivalent, and why Stop and Notification want two different sounds.