Repository files navigation

Your Claude Code sessions, now with sound effects.

Spending hours watching Claude Code work gets mind-numbing. Claudio fixes that by playing sounds when stuff happens. Claude runsgit commit? You get a sound. File operation fails? Different sound. It's like having a very quiet DJ for your AI coding session.

The cool part is how smart it gets. When Claude runsgit commit -m "fix bug", Claudio doesn't just play a generic "bash command" sound. It knows Claude is doing git stuff, specifically a commit, and picks sounds accordingly. If that specific sound doesn't exist, it falls back through git → bash → generic success → default. Nobody wants silence when their AI assistant's code works.

go install claudio.click/cmd/claudio@latestclaudio install

That's it. The install command finds your Claude Code settings and adds the hooks automatically.

Or manually configure Claude Code:

{"hooks": {"PostToolUse":"claudio","PreToolUse":"claudio","UserPromptSubmit":"claudio"  }}

For tool completion (PostToolUse), when Claude runsgit commit:

1. Look for: success/git-commit-success.wav2. Not found? Try: success/git-success.wav  3. Still nothing? Try: success/bash-success.wav4. Nope? Try: success/tool-complete.wav5. Come on: success/success.wav6. Fine: default.wav

For tool startup (PreToolUse), the fallback is more detailed:

1. Look for: loading/git-commit-start.wav2. Not found? Try: loading/git-commit.wav  3. Still nothing? Try: loading/git-start.wav4. Nope? Try: loading/git.wav (command-only)5. How about: loading/bash-start.wav6. Maybe: loading/bash.wav  7. OK: loading/tool-start.wav8. Come on: loading/loading.wav9. Fine: default.wav

You can be as specific or as lazy as you want with your sound pack. Got a sound for every git subcommand? Great. Just want success/error/loading sounds? That works too.

Before a tool runs - plays "start" sounds

• git-commit-start.wav if you're committing
• git-start.wav orbash-start.wav fallbacks
• loading.wav if nothing else matches

After success - plays success sounds

• git-commit-success.wav →git-success.wav →bash-success.wav → etc.

After errors - plays error sounds

• git-error.wav when git fails
• bash-error.wav for general bash failures
• error.wav when all else fails

When you send Claude a message - plays interaction sounds

• prompt-submit.wav →interactive.wav

The parsing is pretty clever. It knows thatnpm install express should trigger npm sounds, not just bash sounds. Same with docker, cargo, go test, whatever.

By default, Claudio just works. It automatically detects your platform and uses system sounds:

• macOS: Uses built-in system sounds like Glass.aiff, Purr.aiff, Hero.aiff
• Windows: Uses Windows Media sounds (Windows Ding.wav, Windows Error.wav, etc.)
• WSL: Maps to Windows sounds via/mnt/c/Windows/Media/
• Linux: Falls back to basic directory soundpack

No setup required - install and sounds work immediately.

If you want custom sounds, the default directory structure is:

loading/     # stuff that's about to happensuccess/     # stuff that worked  error/       # stuff that didn't workinteractive/ # you did somethingdefault.wav  # the sound of giving up

You can make your own soundpack two ways:

Directory soundpack: Organize files the same way and point to it in the config.

JSON soundpack: Map virtual sound paths to any actual files on your system:

{"name":"my-custom-sounds","description":"Maps to my favorite sounds","mappings": {"success/git-commit-success.wav":"/System/Library/Sounds/Glass.aiff","success/bash-success.wav":"/usr/share/sounds/alsa/Front_Right.wav","error/bash-error.wav":"/mnt/c/Windows/Media/Windows Error.wav","loading/loading.wav":"/home/user/my-sounds/thinking.mp3","default.wav":"/usr/share/sounds/alsa/Front_Center.wav"  }}

This way your sounds can be anywhere on the filesystem - no need to copy or reorganize files.

Lives in/etc/xdg/claudio/config.json:

{"volume":0.5,"default_soundpack":"default","soundpack_paths": [],"enabled":true,"log_level":"warn","audio_backend":"auto","file_logging": {"enabled":true,"filename":"","max_size_mb":10,"max_backups":5,"max_age_days":30,"compress":true  }}

Or use environment variables if you're into that:

export CLAUDIO_VOLUME=0.7export CLAUDIO_ENABLED=false# for when you need quiet

Command line works too:

claudio --volume 0.8claudio --silent# just pretend to work

# Claude runs: git status# Claudio plays: loading/git-start.wav, then success/git-success.wav# Claude runs: git commit (but forgot to stage files)# Claudio plays: loading/git-commit-start.wav, then error/git-commit-error.wav# Claude runs: npm test (tests fail)# Claudio plays: loading/npm-test-start.wav, then error/npm-test-error.wav

The JSON that Claude Code sends looks like this:

{"hook_event_name":"PostToolUse","tool_name":"Bash","tool_input": {"command":"git commit -m 'fix'"},"tool_response": {"stdout":"committed","stderr":""}}

Claudio parses that, figures out you ran git commit, checks if it worked (no stderr), and plays the right success sound.

Uses malgo for audio because cross-platform audio in Go is otherwise a nightmare. Preloads sounds into memory so there's no delay when playing them. Supports WAV, MP3, and AIFF formats.

The command parsing knows about git, npm, docker, cargo, go, pip, yarn, kubectl, and more. It can extract subcommands sodocker build gets different sounds thandocker run.

Follows XDG directory specs and includes comprehensive test coverage.

go build -o claudio.

Tests:

gotest ./...

Debug what's happening:

export CLAUDIO_LOG_LEVEL=debugecho'...'| claudio

No sound? Check your volume isn't zero and your audio system works.

Wrong sounds? Turn on debug logging and see what fallback chain it's using.

Something broken? Logs are at~/.cache/claudio/logs/claudio.log

Silence is golden?export CLAUDIO_ENABLED=false

Everygit push deserves a victory sound. Every failed test deserves a sad trombone. Claudio delivers both.

Built with comprehensive test coverage and structured logging.