Notifying Yourself with Notification Hooks

When you kick off a long task, you do not want to babysit the terminal. A Notification hook lets Claude Code tap you on the shoulder, with a desktop alert or a sound, the moment it needs you.

When it fires

The Notification event fires when Claude Code sends a notification, such as when it is waiting on your input. Attaching a hook here turns that internal signal into something you actually notice from another window.

A desktop alert

On macOS you can trigger a native notification:

{
  "hooks": {
    "Notification": [
      { "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude needs you\" with title \"Claude Code\"'" }] }
    ]
  }
}

On Linux, notify-send "Claude Code" "needs your input" does the same job.

Just play a sound

Sometimes a chime is enough:

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

Using the event data

Like every hook, this one receives the event as JSON on stdin. You can pull the message out and show it, so the alert says what Claude actually wants:

#!/usr/bin/env bash
msg=$(jq -r '.message')
notify-send "Claude Code" "$msg"

Why it is worth it

The whole point of headless-friendly, long-running tasks is that you can walk away. A notification hook makes that safe. Start a big refactor, switch to email or another repo, and let the alert bring you back exactly when Claude hits a decision it needs you for, instead of losing minutes to checking a silent terminal.