Claude Code Hook Recipe: Desktop Notification + Sound on Stop

## What This Is / What Problem It Solves The most wasted resource in a long-running task isn't the AI's time—it's your attention. You send Claude Code off to run a refactor or test suite that takes several minutes, and then you keep glancing at the terminal, worried it already finished and is waiting on you, or that it's stuck on some question. This Stop hook automates that: as soon as Claude finishes a turn, it fires a desktop notification and plays a sound. You can safely switch over to read documentation, reply to messages, or grab coffee, and it will actively 'call' you back when done. This is one of those rare 'set up once, benefit every day' productivity tweaks. ## Why This Source Is Worth Using 'Play a sound / notify when done' is a classic hooks use case, backed here by two openly-licensed implementations: rohitg00/awesome-claude-code-toolkit (Apache-2.0) includes `claude-sounds`, which uses macOS's `afplay` to play sounds for about 10 lifecycle events (including task completion); decider/claude-hooks (MIT) provides a dedicated Stop-event 'Task Completion Notifier' that sends a notification when Claude finishes. I combined the concepts from both into one 'cross-platform' script: it auto-detects macOS / native Linux / WSL and uses afplay+osascript, paplay/aplay+notify-send, or PowerShell respectively, so you get the same setup working no matter which environment you're in. ## How to Use It (Steps) 1. Merge the JSON into `~/.claude/settings.json` (globally, so every project gets notifications). Note that a Stop hook usually doesn't need a `matcher`. 2. Create `notify-on-stop.sh`, paste in the script, and `chmod +x` it. 3. Set `{{NOTIFY_TITLE}}` and `{{NOTIFY_MESSAGE}}` (e.g., 'Claude Code' / 'Task complete ✅'). 4. Fill in the sound path per platform: macOS uses `{{MAC_SOUND_PATH}}` (e.g., `/System/Library/Sounds/Glass.aiff`); Linux uses `{{LINUX_SOUND_PATH}}` (pointing to any .wav file). 5. Make sure `notify-send` is available on Linux desktops (usually in the `libnotify-bin` package); for WSL desktop toasts, install the BurntToast PowerShell module—without it you'll still at least get a beep. 6. Test it: have the AI do something small, wait for it to stop, and you should hear a 'ding' plus see a notification. ## Key Points and When to Use - **Stop and Notification are two different events**: Stop means 'this turn ended'; Notification means 'needs your input or approval.' Assigning different sounds to each event lets you audibly tell 'it's actually done' apart from 'it's waiting for my confirmation.' - **Wrap everything in `|| true`**: on a machine without the sound-playing tool installed, the hook shouldn't error out over it—a failed notification should just mean no sound, not a broken main flow. - **When to use**: most useful for long test runs, big refactors, batch data processing, or when you habitually multitask across many windows. It's fine for short interactions too, but you might find it too noisy—in that case, only enable it for specific projects (project-level settings.json). 📎 Source: `claude-sounds` from rohitg00/awesome-claude-code-toolkit (author: Rohit Ghumare, Apache-2.0 license), and the Stop-event Task Completion Notifier from decider/claude-hooks (author: decider, MIT license) — this piece is a Traditional Chinese adaptation combining both into a cross-platform Stop notification + sound setup; see the links above for the originals.

填下面的欄位，上方 prompt 會即時替換 [方括號] 內容。填好後按「複製組好的 prompt」直接丟進工具。

# 目標：Claude Code 跑完一輪（Stop 事件）就桌面通知＋播音效
# 放到 ~/.claude/settings.json（全域，所有專案通用）。
# 機制：Stop hook 在 Claude 結束回應時觸發；可同時跳通知與播聲音。
#       下面腳本自動判斷作業系統，挑對的通知/播音指令。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash {{HOOKS_DIR}}/notify-on-stop.sh"
          }
        ]
      }
    ]
  }
}

# ---- notify-on-stop.sh ----
# chmod +x 後使用。跨平台：macOS 用 afplay + osascript；Linux 用 paplay/aplay + notify-send；Windows(WSL) 用 PowerShell。
#!/usr/bin/env bash
set -euo pipefail

TITLE="{{NOTIFY_TITLE}}"          # 例：Claude Code
MESSAGE="{{NOTIFY_MESSAGE}}"      # 例：任務完成，回來看看 ✅

case "$(uname -s)" in
  Darwin)   # macOS
    afplay {{MAC_SOUND_PATH}} >/dev/null 2>&1 || true   # 例：/System/Library/Sounds/Glass.aiff
    osascript -e "display notification \"$MESSAGE\" with title \"$TITLE\" sound name \"Glass\"" >/dev/null 2>&1 || true
    ;;
  Linux)
    if grep -qi microsoft /proc/version 2>/dev/null; then
      # WSL：呼叫 Windows 端 PowerShell 播音＋通知
      powershell.exe -c "[console]::beep(880,300); New-BurntToastNotification -Text '$TITLE','$MESSAGE'" >/dev/null 2>&1 \
        || powershell.exe -c "[console]::beep(880,300)" >/dev/null 2>&1 || true
    else
      # 原生 Linux
      command -v paplay >/dev/null 2>&1 && paplay {{LINUX_SOUND_PATH}} >/dev/null 2>&1 \
        || (command -v aplay >/dev/null 2>&1 && aplay {{LINUX_SOUND_PATH}} >/dev/null 2>&1) || true
      command -v notify-send >/dev/null 2>&1 && notify-send "$TITLE" "$MESSAGE" >/dev/null 2>&1 || true
    fi
    ;;
  *)        # 其他（含 Git Bash on Windows）：盡量響個鈴
    printf '\a' || true
    ;;
esac
exit 0
# 小技巧：想分辨「完成」vs「需要你輸入」，可另外掛 Notification 事件用不同聲音，
#         這樣聽聲音就知道該回來按核准、還是任務真的做完了。