claude-code-sounds

claude-code-sounds

Sound themes for Claude Code lifecycle hooks.

Plays sound effects when sessions start, prompts are submitted, responses finish, errors occur, and more.

Ships with 17 themes. Bring your own sounds or create new ones.

_"Something need doing?"_

Quick Start

The interactive installer checks dependencies, lets you pick a theme, and optionally customize which sounds map to each hook — all in the terminal.

Requires macOS (uses afplay) and Node.js 20+.

Alternative: install from source

The bash installer requires jq (brew install jq).

Themes

Each theme maps sounds across all 11 Claude Code lifecycle events.

Usage

Muting

Mute sounds without uninstalling — three ways:

- Slash command (inside Claude Code): type /mute or /unmute
- CLI flag: npx claude-code-sounds --mute or --unmute
- Interactive menu: run npx claude-code-sounds and select "Mute sounds" / "Unmute sounds"

Muting creates a sentinel file at ~/.claude/sounds/.muted. The hook script checks for it and exits immediately, so there's zero overhead when muted.

Do Not Disturb

Sounds are automatically muted when active video calls are detected (Zoom, FaceTime, Webex). This is enabled by default.

Edit ~/.claude/sounds/.dnd to add or remove app names — one process name per line, # for comments.

To disable: npx claude-code-sounds --no-dnd or use the interactive menu. Re-enable with --dnd.

Customizing

Re-run with --mix to open the sound assignment grid, where you can reassign sounds to hooks, add themes, or preview clips:

You can also drop any .wav or .mp3 into the sound directories manually:

The script picks randomly from whatever files are in each directory.

Uninstalling

This removes all sound files, the hook script, and the hooks config from settings.json.

How It Works

A single…