Issue Station
Sign In
Tools hereToolbox

claude-code - ✅(Solved) Fix [FEATURE] Add notify-on-complete plugin — ready-to-use Stop hook for completion notifications [1 pull requests, 1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#45619•Fetched 2026-04-10 03:44:22
View on GitHub
Comments
0
Participants
1
Timeline
5
Reactions
0
Author
FuturizeRushFuturizeRush
Participants
FuturizeRushFuturizeRush
Timeline (top)
labeled ×3cross-referenced ×1referenced ×1

Fix Action

Fixed

PR fix notes

PR #45621: feat: add notify-on-complete plugin

Description (problem / solution / changelog)

Summary

Adds a notify-on-complete plugin — a ready-to-use Stop hook that notifies users when Claude finishes responding.

Closes #45619

Motivation

The Stop hook mechanism is powerful, but writing a correct notification script requires handling:

  • UTF-8 text in osascript (using on run argv instead of system attribute)
  • Cross-platform tool detection (macOS vs Linux)
  • Background process safety (( cmd & ) subshell wrapping)
  • Guaranteed {"decision":"approve"} output (trap EXIT)
  • Injection prevention in user-configured messages

This plugin packages all of that into an install-and-go experience.

Features

Three independently toggleable notification modes:

ModemacOSLinux
Soundafplaypaplay / pw-play / aplay
Desktop notificationosascriptnotify-send
Text-to-speechsay (multi-language)espeak-ng / espeak

9 environment variables for customization (sound name, custom sound file, notification text, speech text, voice, etc.). Desktop notification and speech text can be set independently — e.g. desktop shows "Task complete" while voice says "做好了".

Test plan

  • Default (sound + notification) — Glass sound plays, notification appears
  • Sound only (NOTIFY_DESKTOP=0) — sound plays, no notification
  • Notification only (NOTIFY_SOUND=0) — notification appears, no sound
  • Text-to-speech (NOTIFY_SAY=1) — Samantha/Meijia speaks message
  • Custom sound file (NOTIFY_SOUND_FILE=/path/to/file) — plays custom file
  • CJK text in notification — no mojibake (verified with Chinese/Japanese)
  • Non-existent sound file — silently skipped, exit 0
  • All disabled — silent, exit 0, approve output

Changed files

  • plugins/README.md (modified, +1/-0)
  • plugins/notify-on-complete/.claude-plugin/plugin.json (added, +9/-0)
  • plugins/notify-on-complete/README.md (added, +99/-0)
  • plugins/notify-on-complete/hooks/hooks.json (added, +16/-0)
  • plugins/notify-on-complete/hooks/notify.sh (added, +91/-0)

Code Example

{
  "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"
  }
}
RAW_BUFFERClick to expand / collapse

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 handling — osascript'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.

extent analysis

TL;DR

Implement a notify-on-complete plugin to provide a configurable Stop hook with built-in safety measures for cross-platform notification and sound playback.

Guidance

  • Review the proposed notify-on-complete plugin implementation to ensure it addresses the listed challenges, including UTF-8 handling, cross-platform detection, background process safety, guaranteed approve output, and injection prevention.
  • Verify that the plugin is fully configurable via environment variables to accommodate different user preferences for sound, notification, and text-to-speech settings.
  • Test the plugin on both macOS and Linux platforms to ensure seamless detection and usage of available sound and notification tools.
  • Evaluate the plugin's support for international voices and separate text for notification versus speech to cater to diverse user needs.

Example

No code snippet is provided as the issue does not contain explicit code that needs modification or implementation.

Notes

The proposed plugin aims to simplify the process of creating a "ding when done" notification system, but its effectiveness and compatibility depend on thorough testing and review of the implementation.

Recommendation

Apply the proposed notify-on-complete plugin as it seems to address the complexities and safety concerns associated with creating a cross-platform notification system, providing a convenient and configurable solution for users.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#environment variable#ISR setup#authentication setup#request error#file not found

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING