Claude Code Sound 🔔

Sound notifications for Claude Code — with your own audio, per hook.

Claude Code Sound plays a sound when:

• Claude requests permission
• Claude waits for your input
• Claude completes a task

Each one gets its own sound, and you can use any audio file you like.

Installation

npx claude-code-sound install

Want to pick your sounds right away:

npx claude-code-sound install -i

Hooks

| Hook | Fires when | Default sound | | --- | --- | --- | | permission | Claude asks for approval | Funk | | input | Claude waits for your input | Basso | | stop | Claude finishes a task | Glass |

Choosing sounds

claude-code-sound set          # pick a hook, then a sound
claude-code-sound set stop     # pick a sound for one hook

Arrow up and down through the list — each sound plays as you land on it, so you hear it before you commit. Press ⏎ to keep it.

  Sound for "Permission request"
  Claude asks for approval · ● is the current sound

    ● Default — Funk
      Basso
  ❯   Blow          ← playing
      Bottle
      …
      📁 Choose an audio file from your Mac…

  ↑↓ move · ⏎ select · space replay · esc cancel

Or set it directly:

claude-code-sound set stop Hero
claude-code-sound set permission ~/Music/alert.mp3
claude-code-sound set input default

Every change takes effect immediately — no reinstall needed.

Your own audio

Pick 📁 Choose an audio file from your Mac… at the bottom of the sound list and a normal macOS file dialog opens — no typing paths.

The same dialog from the command line:

claude-code-sound add                  # opens the file chooser
claude-code-sound add ~/Downloads/ding.mp3
claude-code-sound set stop ding

Your file is copied into ~/.claude/sounds/, so it keeps working even if you move or delete the original, and it shows up in the picker from then on.

Supported formats: .aiff .aif .wav .mp3 .m4a .aac .caf

Commands

claude-code-sound install [-i]         # install hooks
claude-code-sound set [hook] [sound]   # choose a sound, previewed live
claude-code-sound add [file] [name]    # add your own audio (file chooser)
claude-code-sound list                 # current + available sounds
claude-code-sound test [hook]          # hear the configured sounds
claude-code-sound doctor               # check the setup
claude-code-sound uninstall [--purge]  # remove hooks

Doctor

Checks Claude Code, settings.json, every hook registration, that each configured sound file still exists, and plays a test sound.

Uninstall

Removes only Claude Code Sound's hooks — any other hooks you have configured on the same events are left alone. Your sound choices are kept so a reinstall restores them; add --purge to remove those and your sound library too.

Where things live

~/.claude/settings.json             hook registration
~/.claude/hooks/claude-*-sound.sh   generated hook scripts
~/.claude/claude-code-sound.json    your sound choices
~/.claude/sounds/                   your audio files
~/.claude/claude-code-sound.log     hook activity log

Requirements

• macOS
• Claude Code
• Node.js 16+

License

MIT