A simple CLI tool to get sound and desktop notifications for Claude Code events

Get instant feedback when Claude Code triggers different events - with customizable sounds and desktop notifications for each event!

CCNudge supports all official Claude Code hook events:

• Stop - When Claude finishes responding (most common)
• SubagentStop - When subagent tasks complete
• PostToolUse - After tool calls complete
• PreToolUse - Before tool calls (can be used for alerts)
• UserPromptSubmit - When user submits a prompt
• Notification - When Claude sends notifications
• SessionStart - When session starts/resumes
• SessionEnd - When session ends
• PreCompact - Before compact operations

You can configure different sounds for each event during setup!

npm install -g ccnudge

The interactive setup will run automatically after installation! You'll be prompted to:

• Select which Claude Code events to configure
• Choose notification sounds for each event (system sounds or custom files)
• Test sounds before saving
• Enable desktop notifications per event (optional)

npm install ccnudge
npx ccnudge setup

For global install, setup runs automatically during installation. You can also run setup anytime:

ccnudge setup

That's it! Now Claude Code will notify you when tasks complete.

Interactive setup wizard - walks you through:

• Selecting which Claude Code events to configure
• Choosing notification sounds for each event (system sounds or custom)
• Testing sounds before saving
• Enabling desktop notifications per event (optional)

ccnudge setup

Enable notifications (uses your saved configuration)

# Enable all configured events
ccnudge start
# Enable a specific event
ccnudge start -e Stop

Disable notifications temporarily (keeps your configuration for later)

# Disable all events
ccnudge stop
# Disable a specific event
ccnudge stop -e PostToolUse

Check if CCNudge is enabled and view current configuration

ccnudge status

Output example:

📊 CCNudge Status:
Status: ✅ ENABLED for 2 event(s)
Event: Stop
 Sound: /System/Library/Sounds/Glass.aiff
 Desktop Notifications: ✅ Enabled
Event: PostToolUse
 Sound: /System/Library/Sounds/Tink.aiff
 Desktop Notifications: ❌ Disabled

Test both sound and desktop notification

ccnudge notify

Test just the sound notification

# Test configured sound
ccnudge test
# Test a specific sound
ccnudge test -s Glass

List all available system sounds

ccnudge list

Remove CCNudge configuration completely (with confirmation prompt)

ccnudge remove

# 1. Install globally (setup runs automatically!)
npm install -g ccnudge
# 2. Use Claude Code normally - you'll get notifications!
# 3. Need to focus? Disable temporarily
ccnudge stop
# 4. Re-enable when ready
ccnudge start
# 5. Want to change settings?
ccnudge setup

$ ccnudge setup
👋 Welcome to CCNudge setup!
Get notified when Claude Code triggers different events.
You can configure different sounds for each event and use custom audio files.
? Which events would you like to configure? (Press <space> to select, <a> to toggle all, <i> to invert selection)
❯◉ Stop - When Claude finishes responding
 ◯ SubagentStop - When subagent tasks complete
 ◉ PostToolUse - After tool calls complete
 ◯ PreToolUse - Before tool calls (advanced)
 ◯ UserPromptSubmit - When user submits a prompt
 ◯ Notification - When Claude sends notifications
 ◯ SessionStart - When session starts/resumes
 ◯ SessionEnd - When session ends
 ◯ PreCompact - Before compact operations
📌 Configuring Stop event:
? Choose notification sound for Stop:
❯ Default (/System/Library/Sounds/Glass.aiff)
 Basso
 Glass
 Hero
 Ping
 Custom path...
? Test this sound? Yes
? Enable desktop notifications for Stop? Yes
Testing sound...
✅ Sound played successfully!
Testing desktop notification...
✅ Desktop notification sent!
✅ Configured Stop event to play: /System/Library/Sounds/Glass.aiff
✅ Desktop notifications enabled
📌 Configuring PostToolUse event:
? Choose notification sound for PostToolUse: Tink
? Test this sound? No
? Enable desktop notifications for PostToolUse? No
✅ Configured PostToolUse event to play: /System/Library/Sounds/Tink.aiff
✨ Setup complete! CCNudge is now active for 2 event(s).
Commands:
 ccnudge stop - Temporarily disable all notifications
 ccnudge start - Re-enable all notifications
 ccnudge status - Check current status
 ccnudge notify - Test notification + sound

• Uses afplay for audio playback
• Uses osascript for desktop notifications
• Default sound: Glass.aiff
• System sounds: /System/Library/Sounds/
• Supported formats: .aiff, .wav, .mp3

• Uses paplay (PulseAudio) for audio
• Uses notify-send for desktop notifications
• Default sound: complete.oga
• System sounds: /usr/share/sounds/
• Supported formats: .oga, .wav, .mp3

• Uses PowerShell's Media.SoundPlayer for audio
• Uses BurntToast module for desktop notifications
• Default sound: Windows Notify System Generic.wav
• System sounds: C:\Windows\Media\
• Supported formats: .wav

CCNudge configures the hooks feature in Claude Code's settings file (~/.claude/settings.json). When you run setup, it creates hooks for the events you select. Each event can have its own sound and desktop notification settings.

Example configuration with multiple events:

{
 "hooks": {
 "Stop": [
 {
 "hooks": [
 {
 "type": "command",
 "command": "afplay /System/Library/Sounds/Glass.aiff"
 },
 {
 "type": "command",
 "command": "osascript -e 'display notification \"Claude Code has finished\" with title \"CCNudge\"'"
 }
 ]
 }
 ]
 }
}

CCNudge intelligently manages your configuration:

• Install: Automatically runs setup on global install
• Setup: Creates new configuration and backs up any existing one
• Stop: Disables notifications but saves configuration to ~/.claude/.ccnudge-backup.json
• Start: Restores configuration from backup
• Remove: Completely removes configuration and backups
• Uninstall: Automatically cleans up all CCNudge settings from Claude Code

This means you can safely toggle notifications on/off without losing your settings! When you uninstall CCNudge with npm uninstall -g ccnudge, it automatically removes all configuration from your Claude Code settings.

Check if the sound file exists and is accessible:

# macOS
ls -l /System/Library/Sounds/
# Test sound directly
afplay /System/Library/Sounds/Glass.aiff

macOS: Grant Terminal/iTerm notification permissions in System Preferences > Notifications

Linux: Ensure notify-send is installed:

sudo apt-get install libnotify-bin # Debian/Ubuntu
sudo yum install notify-send # RedHat/Fedora

Windows: Install BurntToast module:

Install-Module -Name BurntToast

ccnudge status
cat ~/.claude/settings.json

ccnudge remove
ccnudge setup

You can also use CCNudge in your own Node.js scripts:

const ccnudge = require('ccnudge');
async function setupMyNotification() {
 // Set up with sound + desktop notification
 await ccnudge.setupNotification('Stop', '/path/to/sound.wav', true);
 // Test
 await ccnudge.testSound();
 await ccnudge.testDesktopNotification();
 // Check status
 await ccnudge.getStatus();
 // Disable temporarily
 await ccnudge.disableNotifications();
 // Re-enable
 await ccnudge.enableNotifications();
}

No! CCNudge only modifies the hooks for events you configure and preserves all other settings.

Yes! During setup, choose "Custom path..." and provide the full path to any audio file.

Yes! During setup, select multiple events and configure each one with its own sound and notification settings.

Stop is the most common - it triggers when Claude finishes responding. You'll hear it when I finish answering your questions (like right now!).

PostToolUse is great for hearing when tools complete. Other events are more advanced - experiment to see what works for you!

Your previous configuration is backed up automatically, and you can restore it with ccnudge start.

Yes! Use ccnudge stop -e EventName to disable a specific event, or ccnudge stop to disable all.

When you run npm uninstall -g ccnudge, the package automatically removes all CCNudge configuration from your ~/.claude/settings.json file, leaving your other Claude Code settings intact. You'll see a cleanup message during uninstall.

MIT

• npm package
• GitHub Repository
• Claude Code Documentation