Claudio

Claudio is a hook-driven audio layer for coding agents. It listens to hook events from Claude Code, OpenAI Codex CLI, Gemini CLI, Qwen Code, GitHub Copilot CLI, Command Code, and OpenCode, maps the event to a contextual sound, and plays that sound without making the agent wait for playback.

It can play different sounds for tool starts, tool successes, tool failures, prompts, notifications, completions, compaction, session starts, and subagent events. Bash commands are parsed, so git commit, npm test, and go build can each have their own sounds instead of sharing one generic shell sound.

Full documentation starts at docs/index.md.

Install

Download the binary for your platform from GitHub Releases, rename it to claudio (claudio.exe on Windows), and put it on PATH. These binaries include the native audio backend; no Go or C compiler is needed. On macOS and Linux, make the downloaded binary executable with chmod +x.

To build from source, install Go 1.25.13 or later. No C compiler is required:

go install claudio.click/cmd/claudio@latest

Native playback uses Oto on Windows, macOS, and Linux, including builds with CGO_ENABLED=0. See installation for runtime audio requirements and run claudio status to check backend availability.

Install hooks for detected agents:

claudio install

claudio install uses --agent auto --scope global by default. It detects Claude Code, Codex CLI, Gemini CLI, Qwen Code, GitHub Copilot CLI, Command Code, and OpenCode, then installs hooks for the agents it finds. To force a single agent:

claudio install --agent claude --scope global
claudio install --agent codex --scope global
claudio install --agent gemini --scope global
claudio install --agent qwen --scope global
claudio install --agent copilot --scope global
claudio install --agent commandcode --scope global
claudio install --agent opencode --scope global

After Codex hook installation, run /hooks in Codex and trust the Claudio hook. OpenCode has no settings hooks, so --agent opencode writes a small plugin to ~/.config/opencode/plugins/claudio.js instead. Use --scope project instead of --scope global when you want hooks only for the current repository. For Claude Code, a global install writes to $CLAUDE_CONFIG_DIR/settings.json when that variable is set, and to ~/.claude/settings.json otherwise.

Daily Commands

claudio status
claudio volume 0.4
claudio mute
claudio unmute
claudio uninstall --agent all --scope global

Optional agent command artifacts:

claudio install-commands --agent claude       # /claudio in Claude Code
claudio install-commands --agent codex        # $claudio skill in Codex
claudio install-commands --agent antigravity  # Antigravity skill and CLI command

Soundpacks

Claudio ships platform defaults and supports three custom soundpack forms:

• Directory soundpacks under loading/, success/, error/, interactive/, completion/, and system/
• JSON soundpacks that map Claudio sound keys to files anywhere on disk
• Managed git soundpacks installed with claudio soundpack add

Useful commands:

claudio soundpack list
claudio soundpack init my-pack --from-platform
claudio soundpack validate ./my-pack.json
claudio soundpack install ./my-pack.json --default
claudio soundpack add gh:owner/repo --name my-pack --default
claudio soundpack update --all

Supported audio formats are WAV, MP3, and AIFF. See docs/soundpacks.md for layout, fallback chains, JSON mappings, validation, and git-backed soundpacks.

Tracking

Sound tracking is enabled by default. Claudio records resolved sounds and missing fallback candidates in a SQLite database under the XDG cache directory, then exposes that data through:

claudio analyze usage --show-summary --show-chains
claudio analyze missing --preset last-week

Use these reports to decide which sounds your custom pack should add next.

Remote Sessions

If the agent runs on a remote machine over SSH, that box usually has no audio device and Claudio stays silent. Forward a PulseAudio socket from your local machine (WSLg on Windows already provides one) and point the remote box at it. See docs/remote-audio-ssh.md.

Build And Test

go build ./cmd/claudio
go test ./...

The Makefile wraps the common workflows; run make help to list targets such as make ci, make smoke, and make release-check. Release notes live in CHANGELOG.md.