Claude Code Audio Hooks
Get notified when Claude Code finishes tasks or needs your attention.
Audio, desktop notifications, and text-to-speech - all platforms.
Promotional Video
https://github.com/user-attachments/assets/3504d214-efac-4e01-84c0-426430b842d6
Built entirely with code using Remotion, Claude Code, ElevenLabs & Suno.
Source: claude-code-audio-hooks-promo-video
Previous version
https://github.com/user-attachments/assets/e314be82-8c88-4026-997e-d25168ac9f5c
Installation Guide
⚠ This is an installation demonstration of the older version, so the installation speed is relatively slow. The new version now installs extremely quickly, giving you a lightning-fast experience! 😉
https://github.com/user-attachments/assets/a9919363-f76c-4dd2-9141-e1c681573d75
Effects Comparison
📷 Effects before version v4.0.0
https://github.com/user-attachments/assets/107ff48b-9d4f-40fd-9368-e36741b262ed
📷 Effects after version v4.0.0 — Voice Notifications (Default Theme)
Ubuntu
https://github.com/user-attachments/assets/2e2f1046-e690-409c-ba05-e621ded295dd
PowerShell
https://github.com/user-attachments/assets/a1b11528-a248-415f-93d9-7859261d9abd
https://github.com/user-attachments/assets/3fd4c3aa-8204-4a06-be1b-d49dc9bb7cf9
🔔 Non-Voice Chimes (Custom Theme)
Full Demo
https://github.com/user-attachments/assets/25be4d51-8385-4f95-aaac-3cc782b603bf
SessionStart & SessionEnd
https://github.com/user-attachments/assets/9e35f43c-e22b-44e3-8251-35057162f192
PermissionRequest, TaskCompleted & SubagentStop
https://github.com/user-attachments/assets/0a855974-143c-424e-9c22-af2db2728d2f
Quick Setup (30 seconds)
One command. No dependencies. No Python. No cloning.
curl -sL https://raw.githubusercontent.com/ChanMeng666/claude-code-audio-hooks/master/scripts/quick-setup.sh | bash
Restart Claude Code. Done.
This gives you:
- Desktop notification + sound when tasks complete
- Urgent alert when authorization is needed
- Alert when permission dialog appears ("Allow this bash command?")
- Background task completion alerts
To remove:
curl -sL https://raw.githubusercontent.com/ChanMeng666/claude-code-audio-hooks/master/scripts/quick-unsetup.sh | bash
Customize which hooks are active (no clone needed):
# See which hooks are enabled/disabled
curl -sL https://raw.githubusercontent.com/ChanMeng666/claude-code-audio-hooks/master/scripts/quick-configure.sh | bash -s -- --list
# Disable a noisy hook
curl -sL https://raw.githubusercontent.com/ChanMeng666/claude-code-audio-hooks/master/scripts/quick-configure.sh | bash -s -- --disable SubagentStop
# Re-enable it later
curl -sL https://raw.githubusercontent.com/ChanMeng666/claude-code-audio-hooks/master/scripts/quick-configure.sh | bash -s -- --enable SubagentStop
# Keep only specific hooks (disables the rest)
curl -sL https://raw.githubusercontent.com/ChanMeng666/claude-code-audio-hooks/master/scripts/quick-configure.sh | bash -s -- --only Stop Notification
Want custom audio, TTS, or advanced features? See Full Installation below.
Comparison
| DIY Hooks | Quick Setup | Full Install |
|---|
| Setup time | Manual JSON editing | 30 seconds | 2 minutes |
| Dependencies | None | None | Python 3.6+ |
| Desktop notifications | macOS only | All platforms | All platforms |
| Custom MP3 audio | No | System sounds | 22 professional sounds |
| Text-to-speech | No | No | Yes |
| Context-aware alerts | No | No | Yes ("Permission needed for Bash") |
| Debouncing | No | No | Yes |
| Per-hook config | No | No | Yes (22 hook types) |
| Logging/diagnostics | No | No | Yes |
Table of Contents