[FEATURE] Add notify-on-complete plugin — ready-to-use Stop hook for completion notifications

Resolved 💬 2 comments Opened Apr 9, 2026 by FuturizeRush Closed Jun 11, 2026

Problem

The Stop hook mechanism is powerful, but writing a correct completion notification script is surprisingly non-trivial. Users who want a simple "ding when done" need to solve all of these:

  1. UTF-8 handlingosascript's system attribute mangles non-ASCII text (e.g. Chinese, Japanese). Must use on run argv instead.
  2. Cross-platform detection — macOS uses afplay/osascript/say, Linux uses paplay/notify-send/espeak. Script must detect what's available and silently skip what's missing.
  3. Background process safety — Sound playback outlives the hook script. Bare cmd & may get killed by SIGHUP on exit. Needs ( cmd & ) subshell wrapping.
  4. Guaranteed approve output — If the script crashes before printing {"decision":"approve"}, Claude gets stuck. Needs trap EXIT as a safety net.
  5. Injection prevention — User-configured messages containing quotes or special characters can break osascript syntax.

Most users just want "play a sound and show a notification when Claude finishes." They shouldn't need to know any of the above.

Proposal

A notify-on-complete plugin that provides a ready-to-use, configurable Stop hook with:

  • 3 notification modes (independently toggleable): system sound, desktop notification, text-to-speech
  • Cross-platform: auto-detects macOS (afplay, osascript, say) and Linux (paplay/pw-play/aplay, notify-send, espeak)
  • Fully configurable via environment variables — sound name, custom sound file path, notification title/message, voice name (supports international voices: English, Japanese, Korean, French, Portuguese, Chinese TW, Cantonese HK, etc.)
  • Separate text for notification vs speech — e.g. desktop shows "Task complete" while voice says "做好了"
  • All the safety measures listed above built in

Configuration example

Users set preferences in settings.json:

{
  "env": {
    "NOTIFY_SOUND": "1",
    "NOTIFY_DESKTOP": "1",
    "NOTIFY_SAY": "1",
    "NOTIFY_SOUND_NAME": "Hero",
    "NOTIFY_MESSAGE": "Task complete",
    "NOTIFY_SAY_TEXT": "Done!",
    "NOTIFY_VOICE": "Samantha"
  }
}

I have a working implementation ready and will open a PR shortly.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗