How to get notified when Claude Code needs you (or finishes)

Claude Code is at its best when you let it run: give it a task, switch to something else, come back when it is done. The catch is knowing when to come back. Stare at the terminal and you have not really stepped away; ignore it and it sits waiting for a permission you never saw.

You do not have to guess. Claude Code fires a hook the moment it needs you, and another when it finishes. Wire either one to a desktop notification and the terminal comes to you.

The two events that matter

• Notification fires when Claude wants your attention. That means either a permission prompt it cannot answer on its own, or an input prompt that has been sitting idle for a while.
• Stop fires when Claude finishes its turn and hands control back to you.

Between them, they cover the two moments you actually care about: it needs me now, and it is done. Both are configured the same way, in a settings.json file under the hooks key. (If hooks are new to you, start with our complete guide to Claude Code hooks.)

macOS

macOS ships osascript, which can post a real notification to Notification Center:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": "osascript -e 'display notification \"Claude needs you\" with title \"Claude Code\" sound name \"Ping\"'" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "osascript -e 'display notification \"Run finished\" with title \"Claude Code\" sound name \"Glass\"'" }
        ]
      }
    ]
  }
}

The sound name part rings a system sound, so you get an audible cue even if you are not looking at the screen. If you want alerts that stay on screen until you dismiss them, install terminal-notifier and use terminal-notifier -title 'Claude Code' -message 'Claude needs you' instead.

Linux

On most desktops, notify-send is available (from libnotify):

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": "notify-send -u critical 'Claude Code' 'Claude needs you'" }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "notify-send 'Claude Code' 'Run finished'" }
        ]
      }
    ]
  }
}

-u critical keeps the "needs you" alert on screen until you dismiss it, which is what you want for something that is blocking.

Windows and WSL

On Windows, PowerShell can raise a toast through the BurntToast module, but the dependency-free option is a message box:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "powershell -c \"[System.Windows.Forms.MessageBox]::Show('Run finished','Claude Code')\"" }
        ]
      }
    ]
  }
}

Running Claude Code inside WSL? notify-send will not reach the Windows desktop unless you have WSLg. Call PowerShell from the Linux side instead: powershell.exe -c "..." works from any WSL shell.

Say which project pinged

A notification that says "Claude needs you" is useless once you run more than one session. The payload arriving on stdin carries the session's working directory, so a two-line script can name the project:

#!/usr/bin/env bash
# .claude/hooks/notify.sh
payload=$(cat)
project=$(basename "$(echo "$payload" | jq -r '.cwd')")
notify-send -u critical "Claude Code" "$project needs you"

Point the hook at it, and use $CLAUDE_PROJECT_DIR so the path resolves from any subdirectory:

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/notify.sh", "timeout": 10 }
        ]
      }
    ]
  }
}

The same payload also carries session_id, if you would rather key your notifications on the session than on the folder.

Just want a sound?

You do not need a full notification. A single bell in the terminal is often enough:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "printf '\\a'" }] }
    ]
  }
}

There is a per-platform walkthrough in play a sound when Claude Code finishes.

Or let your terminal carry the alert

A desktop notification is not the only option, and in a terminal-heavy setup it is often not the best one. Ringing the bell from the hook lets your multiplexer flag the exact window the event came from:

{
  "hooks": {
    "Notification": [
      { "hooks": [{ "type": "command", "command": "printf '\\a' > /dev/tty" }] }
    ]
  }
}

With set -g monitor-bell on in your ~/.tmux.conf, the status bar highlights the window that needs you, which is more information than a pop-up saying "Claude Code". iTerm2 and most modern terminals can do the same through their own triggers or attention badges.

Notify only when it was actually long

Alerts you get every thirty seconds stop being alerts. If most of your turns are short, gate the notification on how long the turn took, by stamping the start in UserPromptSubmit and checking it in Stop:

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "date +%s > /tmp/claude-start" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "[ $(( $(date +%s) - $(cat /tmp/claude-start) )) -gt 60 ] && notify-send 'Claude Code' 'Long run finished'" }] }
    ]
  }
}

Keep the Notification hook ungated though: something blocking you is always worth interrupting for.

Where scripts run out of road

Notifications work well for one session. Run three or four at once and they start to blur together: which project just pinged? Was that a "needs you" or a "done"? Notification centres also collapse repeats, so a stack of five alerts becomes one line you have to expand. You are back to alt-tabbing to find out.

That is the gap Blooby fills. Instead of a notification per event, it gives each Claude Code session its own animated mascot that reflects its state in real time, driven by these same hooks: it looks up when a session needs permission, celebrates when one finishes, dozes off when a session goes quiet. You glance at the corner of your screen and know which of your sessions wants you, with no config and no scripts to maintain.