Claudio

Claudio is a command-line tool that provides contextual audio feedback during coding-agent sessions. Designed for scenarios where monitoring long-running agents via the terminal is inefficient or where silent failures are undesirable, it plays distinct sounds for various events, helping users stay informed about session progress without needing to watch the screen.

The tool operates as a hook command, reading event data in JSON format from standard input, selecting appropriate sounds through a fallback mechanism, and initiating playback in the background before quickly returning control to the agent. Claudio supports a wide array of hooks, enabling different sounds for actions such as prompt submissions, tool starts, successful edits, failed tests, permission requests, context compaction, and final responses. The specific events covered vary by agent, with detailed hook coverage for agents like Claude Code, Codex CLI, Gemini CLI, Qwen Code, and GitHub Copilot CLI. For example, Claude Code hooks include events such as SessionStart, UserPromptSubmit, TaskCreated, and SessionEnd, among others, with some hooks like MessageDisplay and FileChanged disabled by default to prevent excessive audio feedback.

Installation is streamlined via the command line, with Claudio automatically detecting supported agents and installing the necessary hooks. It preserves existing non-Claudio hooks in agent configuration files and allows for both global and project-specific installations. Users can further control Claudio’s behavior with commands to check status, adjust volume, mute or unmute audio, list available soundpacks, and analyze missing sounds. Optional in-agent control commands can also be installed for certain agents, enabling direct interaction from within the agent’s environment.

Sound selection is context-sensitive, extracting the relevant command and subcommand to choose the most specific sound available through a hierarchical fallback chain. Claudio works without requiring a configuration file, using platform-aware defaults for sound mappings on Windows, macOS, WSL, and Linux. Persistent configuration, when used, is stored in a standard XDG config path appropriate to the operating system. This approach ensures flexibility and ease of use across different development environments.