Skip to content

About

Sound notification hooks for Claude Code on Windows (PowerShell + MCI API)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

3 Commits

Folders and files

Repository files navigation

Claude Code Sound Hooks

Читать на русском

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.

Features

  • 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

How It Works

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

Dynamic Volume (play-stop.ps1)

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.

Installation

Automatic

git clone https://github.com/DImagine/claude-code-sound-hooks.git
cd claude-code-sound-hooks
powershell -ExecutionPolicy Bypass -File install.ps1

The script copies files to ~/.claude/hooks/sounds/ and adds hook entries to ~/.claude/settings.json.

Manual

  1. Copy the contents of sounds/ and hooks/ 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
  1. Add the hooks section 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 .ps1 files.

Configuration

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

Custom Sounds

Replace the .wav files in sounds/ with your own. Format: WAV (recommended); MP3 and other formats are also supported via MCI mpegvideo.

Technical Details

Why MCI instead of SoundPlayer?

  • System.Media.SoundPlayer — no volume control
  • System.Windows.Media.MediaPlayer (WPF) — unreliable playback in CLI context
  • MCI (winmm.dll) — native Windows API with volume control, works reliably

Why silent.wav?

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.

Why CharSet.Auto?

Explicitly calling mciSendStringW doesn't work in PowerShell. CharSet.Auto correctly selects the Unicode version of the function.

Troubleshooting

Hooks don't fire (no sound)

The most likely cause is PowerShell Execution Policy blocking .ps1 scripts. Check the current policy:

Get-ExecutionPolicy -List

If CurrentUser is set to Restricted or Undefined, allow script execution:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Note. The installer (install.ps1) already uses the -ExecutionPolicy Bypass flag 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.

Requirements

  • Windows 10/11
  • PowerShell 5.1+ (pre-installed on Windows)
  • Claude Code with hooks support

Credits

Sound files from the claude-created pack by BMayhew/claude-sound-hooks.

License

MIT

About

Sound notification hooks for Claude Code on Windows (PowerShell + MCI API)

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages