Claude Code Sound Packs

Add sound effects to your Claude Code sessions using hooks. Every action triggers a themed voice line.

Inspired by Delba's post showing Warcraft Peon sounds for Claude Code.

Quick Start

git clone https://github.com/moonshot-partners/claude-code-sound-packs.git
cd claude-code-sound-packs

# Install a pack (copies sounds to ~/.claude/hooks/sounds/)
./install.sh warcraft-peasant

# Preview all sounds
./preview.sh warcraft-peasant

# Activate it
./activate.sh warcraft-peasant

# Start a new Claude Code session and hear the sounds!

Sound files (WAV) are included in the repo so you don't need to download anything. The install.sh script re-downloads from source and converts, but you can also just copy the packs/<name>/sounds/ directory to ~/.claude/hooks/sounds/<name>/ manually.

Available Packs

Pack	Description
warcraft-peasant	Warcraft III Human Peasant - "Ready to work!", "Yes, milord?", "Job's done!"
warcraft-peon	Warcraft III Orc Peon - "Zug zug", "Work work", "Something need doing?"
cnc-generals-gla	C&C Generals GLA Worker - "Okay, okay! I will work!", "AK-47s for everyone!"
cnc-generals-usa	C&C Generals USA - "Made in the US of A!", "I've got a present for ya!"
cnc-generals-china	C&C Generals China - "Let loose the juice!"
mario	Super Mario - "Here we go!", "Okey-dokey!", "Yahoo!"
metal-gear-solid	Metal Gear Solid - "Kept you waiting, huh?", "Alert!", "Mission complete"
zelda	The Legend of Zelda - "Secret found!", "Hey! Listen!", "Quest complete!"

Hook Events

Each pack maps sounds to 8 Claude Code hook events:

Event	When it fires	Example sound
SessionStart	Session begins	"Ready to work!"
UserPromptSubmit	You send a prompt	"Yes, milord?"
Notification	Claude sends a notification	"What?"
Stop	Claude finishes responding	"Job's done!"
SubagentStart	Subagent spawned	"Off I go then!"
SubagentStop	Subagent finishes	"Something need doing?"
TaskCompleted	Task marked complete	"All done!"
SessionEnd	Session terminates	"I'll be back to work!"

Commands

./install.sh <pack-name|all>

Downloads sound files and converts them to WAV format. Installs to ~/.claude/hooks/sounds/<pack-name>/.

Requirements: jq, ffmpeg, curl

# Install one pack
./install.sh warcraft-peasant

# Install all packs
./install.sh all

./preview.sh <pack-name>

Play all sounds in a pack to hear them before activating.

./preview.sh warcraft-peon

./activate.sh <pack-name>

Merges sound hooks into ~/.claude/settings.json. Automatically deactivates any previously active pack.

• Preserves all non-sound hooks (e.g., PermissionRequest)
• Preserves all other settings (statusLine, plugins, MCP servers, etc.)
• Frequent events use async: true so sounds don't block Claude

./activate.sh warcraft-peasant

./deactivate.sh

Removes sound hooks from ~/.claude/settings.json. Only removes events managed by the active pack.

./deactivate.sh

Dependencies

Tool	Install	Purpose
jq	apt install jq	JSON processing
ffmpeg	apt install ffmpeg	Audio conversion
aplay	ALSA utils	Audio playback

Note: Now works on both macOS (afplay) and Linux (aplay)!

How It Works

Claude Code hooks let you run shell commands on specific events. This project:

1. Downloads sound clips from public sources (wowhead CDN, myinstants, etc.)
2. Converts them to WAV format via ffmpeg
3. Creates hook entries in ~/.claude/settings.json that play sounds via aplay (Linux) or afplay (macOS)
4. Tracks which events are managed via a manifest file so deactivation is clean

Your settings.json hooks will look like:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [{ "type": "command", "command": "aplay ~/.claude/hooks/sounds/warcraft-peasant/session-start.wav" }]
      }
    ]
  }
}

Creating Your Own Pack

1. Create a new directory under packs/:

   packs/my-pack/
   ├── pack.json      # Metadata + hook-to-sound mappings
   └── sources.json   # Download URLs for sound files
   

2. Define pack.json:

   {
     "name": "my-pack",
     "displayName": "My Custom Pack",
     "description": "My custom sound effects",
     "sounds": {
       "SessionStart": { "file": "sounds/session-start.wav", "label": "Hello!" },
       "Stop": { "file": "sounds/stop.wav", "label": "Done!" }
     }
   }

3. Define sources.json:

   {
     "format": "mp3",
     "files": [
       { "url": "https://example.com/hello.mp3", "target": "sounds/session-start.wav", "event": "SessionStart" },
       { "url": "https://example.com/done.mp3", "target": "sounds/stop.wav", "event": "Stop" }
     ]
   }

4. Run ./install.sh my-pack and ./activate.sh my-pack

You don't need to map all 8 events - unmapped events simply won't play sounds.

Contributing

PRs welcome! Especially for:

• New sound packs - Movie quotes, game characters, memes, etc.
• Better C&C Generals sources - The USA and China packs need faction-specific voice clips
• Windows support - Replace afplay/aplay with PowerShell audio playback
• Windows support - Replace afplay with PowerShell audio playback

License

MIT - See LICENSE for details.

Sound files are sourced from public fan sites and are property of their respective copyright holders. This project provides tooling only; sound files are downloaded at install time and not distributed with the repository.