claudio

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:

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 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:

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…