Sound notifications for Claude Code on Windows.
Never miss when Claude finishes responding, hits an error, or needs your attention — even when you've switched to another window.
Disclaimer. This project was created by AI based on the author's working setup and adapted for publication with minimal changes. It has not been tested in its current form. Use at your own risk — or simply open this repository in Claude Code and ask it to install the hooks for you. It can handle it.
- 4 sound events — response complete, tool error, permission request, notification
- Dynamic volume — the longer Claude thinks, the louder the notification (linear interpolation)
- Bluetooth/USB speaker wake-up — plays silence before the actual sound to wake up sleeping speakers
- Native Windows — PowerShell + MCI API (
winmm.dll), no external dependencies
| Event | Script | Sound | Description |
|---|---|---|---|
UserPromptSubmit |
save-time.ps1 |
— | Saves the timestamp when a prompt is submitted |
Stop |
play-stop.ps1 |
finished.wav |
Claude finished responding |
PostToolUseFailure |
play-error.ps1 |
error.wav |
A tool call failed with an error |
PermissionRequest |
play-wait.ps1 |
wait.wav |
Claude is asking for permission |
Notification |
play-wait.ps1 |
wait.wav |
Claude sent a notification |
The completion sound volume depends on the response time:
Response time Volume
0 sec ───────────────── 7% ($minVolume)
╲ linear
╲ interpolation
15 sec ──────────────── 30% ($maxVolume)
>15 sec ─────────────── 30% (ceiling)
Configurable via variables at the top of the script: $minSeconds, $maxSeconds, $minVolume, $maxVolume.
git clone https://github.com/DImagine/claude-code-sound-hooks.git
cd claude-code-sound-hooks
powershell -ExecutionPolicy Bypass -File install.ps1The script copies files to ~/.claude/hooks/sounds/ and adds hook entries to ~/.claude/settings.json.
- Copy the contents of
sounds/andhooks/to~/.claude/hooks/sounds/:
~/.claude/hooks/sounds/
├── finished.wav
├── error.wav
├── wait.wav
├── silent.wav
└── hooks/
├── save-time.ps1
├── play-stop.ps1
├── play-error.ps1
└── play-wait.ps1
- Add the
hookssection from settings.example.json to your~/.claude/settings.json, adjusting paths as needed.
Important: All hooks require
"shell": "powershell"— without it, Claude Code will run the script through bash, which cannot execute.ps1files.
Edit the variables at the top of each script:
| Parameter | File | Default | Description |
|---|---|---|---|
$volume |
play-error.ps1, play-wait.ps1 |
300 (30%) |
Sound volume (0–1000) |
$minSeconds |
play-stop.ps1 |
0 |
Minimum response time to trigger sound |
$maxSeconds |
play-stop.ps1 |
15 |
Time after which volume is always at max |
$minVolume |
play-stop.ps1 |
70 (7%) |
Volume for short responses |
$maxVolume |
play-stop.ps1 |
300 (30%) |
Volume for long responses |
Replace the .wav files in sounds/ with your own. Format: WAV (recommended); MP3 and other formats are also supported via MCI mpegvideo.
System.Media.SoundPlayer— no volume controlSystem.Windows.Media.MediaPlayer(WPF) — unreliable playback in CLI context- MCI (
winmm.dll) — native Windows API with volume control, works reliably
Bluetooth and USB speakers enter sleep mode when there's no audio stream. Playing silence at zero volume activates the audio channel and wakes up the speakers before the actual sound plays. [Console]::Beep() doesn't work for this — it doesn't pass through Bluetooth.
Explicitly calling mciSendStringW doesn't work in PowerShell. CharSet.Auto correctly selects the Unicode version of the function.
The most likely cause is PowerShell Execution Policy blocking .ps1 scripts. Check the current policy:
Get-ExecutionPolicy -ListIf CurrentUser is set to Restricted or Undefined, allow script execution:
Set-ExecutionPolicy -Scope CurrentUser RemoteSignedNote. The installer (
install.ps1) already uses the-ExecutionPolicy Bypassflag in hook commands, which should work around this issue. However, if you configured hooks manually with"shell": "powershell", the scripts will be subject to the system execution policy.
- Windows 10/11
- PowerShell 5.1+ (pre-installed on Windows)
- Claude Code with hooks support
Sound files from the claude-created pack by BMayhew/claude-sound-hooks.