Notification Hook for Claude Code (macOS)

Get notified when Claude Code needs your action with native macOS notifications.

Why?

• Works in quiet environments - Know Claude Code's status even in offices or libraries where you can't use sound
• Step away freely - On-screen banners let you check status anytime you return
• Never miss a notification - Banners stay visible until you interact with them (If you miss sound, no worries!)

Works with any terminal app (Terminal.app, iTerm2, Warp, Alacritty, etc.).

Setup (5 minutes)

Step 1: Install terminal-notifier

brew install terminal-notifier

Step 2: Test notifications

terminal-notifier -title "Test" -message "Hello"

If the notification appears, you're good to go. If not, enable notifications in System Settings → Notifications → terminal-notifier.

Step 3: Change notification style to "Alerts"

1. Open System Settings
2. Go to Notifications → terminal-notifier
3. Change notification style to "Persistent" (banners will stay on screen until dismissed)

Step 4: Copy configuration file

# For new installations
cp settings.json ~/.claude/settings.json

# If you already have settings.json, manually merge the "hooks" section

Step 5: Restart Claude Code

Restart Claude Code to apply the settings.

Setup complete!

How It Works

Event	Notification	When
Notification	"Awaiting your input" + sound	Claude Code is awaiting your input or permission
Stop	"Task completed" + sound	Claude Code finishes responding
UserPromptSubmit	Remove notification	User sends a message

Notifications disappear when you send a message, and reappear when Claude needs your attention.

Customizing Sounds

Default sounds:

• Notification (waiting for input): Bottle.aiff
• Stop (task completed): Glass.aiff

Available macOS system sounds:

Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse, Ping, Pop, Purr, Sosumi, Submarine, Tink

Preview a sound on your terminal:

afplay /System/Library/Sounds/Pop.aiff

To change sounds, edit the afplay path in ~/.claude/settings.json:

/usr/bin/afplay /System/Library/Sounds/YOUR_SOUND.aiff

Troubleshooting

terminal-notifier: command not found

brew install terminal-notifier

Notifications disappear too quickly

Change notification style to "Alerts" in System Settings → Notifications → terminal-notifier.

Notifications not appearing

1. Check notification permissions: System Settings → Notifications → terminal-notifier → Enable "Allow Notifications"
2. Check Focus mode: Make sure Focus / Do Not Disturb is disabled
3. Run test command: terminal-notifier -title "Test" -message "Hello"

Technical Notes

The cat > /dev/null; at the beginning of hook commands consumes the JSON data that Claude Code passes via stdin, preventing unwanted terminal output.

License

MIT License - see LICENSE for details.