[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:
- UTF-8 handling —
osascript'ssystem attributemangles non-ASCII text (e.g. Chinese, Japanese). Must useon run argvinstead. - Cross-platform detection — macOS uses
afplay/osascript/say, Linux usespaplay/notify-send/espeak. Script must detect what's available and silently skip what's missing. - Background process safety — Sound playback outlives the hook script. Bare
cmd &may get killed by SIGHUP on exit. Needs( cmd & )subshell wrapping. - Guaranteed approve output — If the script crashes before printing
{"decision":"approve"}, Claude gets stuck. Needstrap EXITas a safety net. - Injection prevention — User-configured messages containing quotes or special characters can break
osascriptsyntax.
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.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗