Examples

These examples are meant to be copied into a terminal and adjusted for your paths.

Each example assumes claudio is already on PATH. See Installation for release binaries and go install.

Install For Claude Code

claudio install --agent claude --scope global
claudio status

Install only for one repository:

cd /path/to/project
claudio install --agent claude --scope project

Install For Codex

claudio install --agent codex --scope global

Then open Codex, run /hooks, and trust the Claudio hook.

Project-only Codex install:

cd /path/to/project
claudio install --agent codex --scope project

Add Agent Control Commands

Claude Code:

claudio install-commands --agent claude

Then use:

/claudio status
/claudio volume 0.35
/claudio mute
/claudio unmute

Codex:

claudio install-commands --agent codex

Then ask Codex to use $claudio.

Preview an install without writing anything:

claudio install --agent all --dry-run

Manually Test A Hook Payload

Prompt event:

echo '{"session_id":"manual","cwd":".","hook_event_name":"UserPromptSubmit","prompt":"test"}' | claudio

Successful Bash event:

echo '{"session_id":"manual","cwd":".","hook_event_name":"PostToolUse","tool_name":"Bash","tool_input":{"command":"git status"},"tool_response":{"stdout":"clean","stderr":"","interrupted":false}}' | claudio

Failed Bash event:

echo '{"session_id":"manual","cwd":".","hook_event_name":"PostToolUse","tool_name":"Bash","tool_input":{"command":"npm test"},"tool_response":{"stdout":"","stderr":"tests failed","interrupted":false}}' | claudio

The first sound should resolve through success/git-status-success.wav; the second through error/npm-test-error.wav. A non-empty stderr marks a Bash result as a failure.

Run without audio:

echo '{"session_id":"manual","cwd":".","hook_event_name":"Stop"}' | claudio --silent

Tune Volume

Persist a quieter default:

claudio volume 0.25

Override the volume for one shell session. Hooks started by an agent launched from this shell inherit it:

export CLAUDIO_VOLUME=0.8
claudio status

Disable and re-enable:

claudio mute
claudio status
claudio unmute

Create A Minimal JSON Soundpack

Create files:

mkdir -p ~/sounds/claudio
# Put real .wav, .mp3, or .aiff files in this directory.

Create ~/sounds/claudio/minimal.json:

{
  "name": "minimal",
  "description": "Small soundpack with category-level fallbacks",
  "version": "1.0.0",
  "mappings": {
    "loading/loading.wav": "./loading.wav",
    "success/success.wav": "./success.wav",
    "error/error.wav": "./error.wav",
    "interactive/interactive.wav": "./interactive.wav",
    "completion/completion.wav": "./completion.wav",
    "system/system.wav": "./system.wav",
    "default.wav": "./default.wav"
  }
}

Validate and install:

claudio soundpack validate ~/sounds/claudio/minimal.json
claudio soundpack install ~/sounds/claudio/minimal.json --default

Create A Directory Soundpack

mkdir -p my-pack/{loading,success,error,interactive,completion,system}
cp /path/to/default.wav my-pack/default.wav
cp /path/to/loading.wav my-pack/loading/loading.wav
cp /path/to/success.wav my-pack/success/success.wav
cp /path/to/error.wav my-pack/error/error.wav
cp /path/to/interactive.wav my-pack/interactive/interactive.wav
cp /path/to/completion.wav my-pack/completion/completion.wav
cp /path/to/system.wav my-pack/system/system.wav

claudio soundpack validate ./my-pack
claudio soundpack install ./my-pack --default

Add specific sounds as you learn what you miss:

success/git-commit-success.wav
error/npm-test-error.wav
loading/go-test-start.wav
completion/agent-complete.wav
system/session-start.wav

Use Tracking To Improve A Pack

After using Claudio for a while:

claudio analyze missing --preset all-time --limit 30

Add sounds for the highest-requested missing keys, validate, and reinstall:

claudio soundpack validate ./my-pack
claudio soundpack install ./my-pack --default

Inspect actual use:

claudio analyze usage --show-summary --show-chains
claudio analyze usage --tool Bash --preset last-week

Managed Git Soundpack

claudio soundpack add gh:owner/repo --name retro --default
claudio soundpack status retro
claudio soundpack update retro

If the pack lives below the repository root:

claudio soundpack add gh:owner/repo --subdir packs/retro --name retro --default

Debug Logging

Debug output goes only to the log file; stderr shows errors only. Run a payload with debug logging, then read the file:

echo '{"session_id":"manual","cwd":".","hook_event_name":"Stop"}' | CLAUDIO_LOG_LEVEL=debug claudio --silent
claudio status   # the "file logging" line shows the log path
tail -n 50 ~/.cache/claudio/logs/claudio.log

The path above is the Linux default. On macOS it is ~/Library/Caches/claudio/logs/claudio.log; on Windows, %LOCALAPPDATA%\cache\claudio\logs\claudio.log.

To keep debug logging on for agent-run hooks, set "log_level": "debug" in config.json.

See Also