How to Get a Notification When Claude Code Finishes a Task

When you give Claude Code a long task and switch to another window, it is easy to miss when it finishes. The Stop hook runs the moment the main agent stops responding, which makes it perfect for a finished notification. This guide adds a sound and a desktop alert on macOS, with notes for other systems.

• Claude Code with hooks support
• A terminal that can run a small shell script
• On macOS, the built-in osascript and afplay commands

Step 1: Write the notification script

Keep it tiny. On macOS, osascript shows a banner and afplay rings a system sound. On Linux you would swap in notify-send; on Windows, a PowerShell toast.

#!/usr/bin/env bash
# macOS: banner + sound when Claude Code stops
osascript -e 'display notification "Task finished" with title "Claude Code"'
afplay /System/Library/Sounds/Glass.aiff 2>/dev/null || true

Step 2: Register it on the Stop event

The Stop event has no tool to match, so the matcher can be empty or omitted. Add it to settings.json under the Stop array.

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

Step 3: Test it

Run any quick request and switch away. When Claude finishes, the banner appears and the sound plays. If nothing happens, run the script directly in your terminal to confirm the notification commands work on your machine.

Result: a hands-off alert every time Claude Code finishes, so you can run long tasks in the background and get pulled back exactly when there is something to look at.