CLI Reference

This page documents the current command surface exposed by claudio.

claudio [flags]
claudio [command]

Global flags:

--volume, --soundpack, and --silent affect hook processing only. They are never written to config.json.

claudio

With no subcommand, Claudio reads a hook JSON payload from stdin and processes it.

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

Required payload fields are:

• session_id
• cwd
• hook_event_name

Tool events can also include tool_name, tool_input, and tool_response. A payload that is not valid JSON or lacks a required field exits with code 1.

claudio install

Installs hooks for Claude Code, Codex CLI, Gemini CLI, Qwen Code, GitHub Copilot CLI, or Command Code, or the OpenCode plugin.

claudio install [flags]

Flags:

--agent auto installs for every agent that shows evidence of being present: its executable is on PATH, its settings file or settings directory exists, or Claudio hooks are already installed there. It fails if no agent is found. --agent all targets all five agents whether or not they are installed.

Settings file locations for each agent and scope are listed on the home page. Claude Code honors CLAUDE_CONFIG_DIR, Codex honors CODEX_HOME, and GitHub Copilot CLI honors COPILOT_HOME.

Examples:

claudio install
claudio install --agent all --scope global
claudio install --agent claude --scope global
claudio install --agent codex --scope project
claudio install --agent gemini --scope global
claudio install --agent qwen --scope global
claudio install --agent copilot --scope global
claudio install --agent codex --scope global --dry-run

Codex users must trust the hook with /hooks after installation.

claudio uninstall

Removes Claudio hooks for Claude Code, Codex CLI, Gemini CLI, Qwen Code, GitHub Copilot CLI, or Command Code, or the OpenCode plugin.

claudio uninstall [flags]

Flags match install:

Only Claudio’s own hook entries are removed. Other hooks in the same settings file are preserved.

claudio install-commands

Installs optional command artifacts for asking an agent to control Claudio.

claudio install-commands --agent claude
claudio install-commands --agent codex
claudio install-commands --agent antigravity

When CLAUDE_CONFIG_DIR is set, the Claude Code command goes to $CLAUDE_CONFIG_DIR/commands/claudio.md instead.

If an artifact already exists and its content is not something Claudio wrote, the command refuses to touch it and exits with an error. Move or delete your customized file first.

claudio uninstall-commands

Removes artifacts created by install-commands. Takes the same --agent flag, also defaulting to claude.

claudio uninstall-commands --agent claude
claudio uninstall-commands --agent codex
claudio uninstall-commands --agent antigravity

claudio status

Prints the effective configuration after file and environment overrides.

claudio status

Example output:

claudio status

  config file:    /home/me/.config/claudio/config.json
  enabled:        true
  volume:         0.50 (from config.json)
  soundpack:      embedded:linux.json
  log level:      warn
  audio backend:  auto -> oto (available; playback not tested)
  file logging:   enabled (/home/me/.cache/claudio/logs/claudio.log)
  tracking:       enabled (/home/me/.cache/claudio/sounds.db)
  forwarding:     off
  version:        1.15.0

The audio backend line shows what auto resolves to and whether that backend is available. It does not play a sound.

When forwarding is set, the forwarding line reads on, to <address> (token set) or (no token). The token is never printed. That machine plays nothing itself, so its backend and tracking lines describe settings it does not use.

When audio is disabled, the enabled line includes the literal word MUTED.

--config selects the file to report on. The transient --volume, --soundpack, and --silent flags are not applied.

claudio volume

Gets or sets the persisted volume in config.json.

claudio volume
claudio volume 0.25

With no argument it prints the volume hooks will use, including a CLAUDIO_VOLUME override if one is set. With an argument it writes the value to the config file.

claudio volume, mute, unmute, and soundpack use write to the file named by --config, or else to the user config path (see Configuration). If that file does not exist yet, they create it from the effective configuration, so the new file is complete.

Environment variable CLAUDIO_VOLUME and global flag --volume still override the persisted value at runtime.

claudio mute And claudio unmute

Persistently toggles enabled in config.json.

claudio mute
claudio unmute

Environment variable CLAUDIO_ENABLED still overrides the persisted value at runtime.

claudio listen

Plays sound events that arrive from somewhere else. Run it where the speakers are; whatever sees the event can be another machine, a container or a cloud session. Events arrive over HTTP, as OpenTelemetry logs, or with --stdin on a pipe.

claudio listen
claudio listen --addr 0.0.0.0:19190 --max-age 10s
<command that prints events> | claudio listen --stdin

The sound is chosen on the listening machine, from its soundpack, volume and mute setting, and is recorded in its tracking database when tracking is on. The global --volume, --soundpack, --silent and --config flags apply.

A Claudio hook on another machine sends its events when that machine has forward.url set; see Forwarding.

Over HTTP

Without --stdin it prints listening on http://<address> and runs until interrupted.

Without a token only a loopback address is accepted, because anyone who can reach the port can play sounds. Prefer --token-file to --token: other users of the machine can read a command line. The two cannot be combined, and a token file that is missing or empty is an error.

Send one JSON event per POST /events:

curl -X POST http://127.0.0.1:19190/events \
  -H "Authorization: Bearer <token>" \
  -d '{"source":"claude","category":"completion","hint":"agent-complete","operation":"stop"}'

These are the names the fallback chains are built from, so an event picks the same sound a local hook with the same values would.

Request bodies are never logged or echoed.

As OpenTelemetry Logs

The same web server is an OpenTelemetry (OTLP) logs receiver at POST /v1/logs, so anything that already exports telemetry can be heard without installing Claudio where it runs. Only the JSON encoding over HTTP is accepted; gzip is fine. The token, --max-age and the limit of eight sounds apply as they do to /events.

To hear Claude Code through its own telemetry, start it with:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:19190
export OTEL_LOGS_EXPORT_INTERVAL=1000
# only if the listener has a token:
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <token>"

Claude Code sends records in batches, every five seconds unless OTEL_LOGS_EXPORT_INTERVAL says otherwise, so these sounds trail the action by up to that long. Its records map onto the events its hooks produce, so one soundpack serves both:

Telemetry says less than a hook does. A shell command is only “Bash” unless Claude Code is told to log tool details, and nothing reports a turn ending or Claude waiting for permission. Where Claudio’s hooks can be installed they are the better source; do not enable both for one session or every sound plays twice.

Records from any other service map by name and outcome:

• The sound hint is the record’s eventName, else its event.name attribute, else a body that is a single identifier such as deploy.finished. A record with none of those is a log line and is skipped.
• The category is error when a success attribute is false or the severity is ERROR or higher, success when success is true, and system otherwise.
• The source is the resource’s service.name.

So a record named deploy.finished with success true looks for success/deploy-finished.wav and falls back to the category sound.

On A Pipe

With --stdin no web server is started. Claudio reads stdin, one JSON event per line in the same format as above, and plays each until stdin ends. What carries the events to the pipe is up to you: an SSH session, a relay’s client, a file being followed.

• Blank lines are skipped, so keep-alive lines from a streaming client are harmless.
• A line that is not an event, has no known category, or is longer than 64 KiB is logged and skipped. The stream continues.
• --max-age and the limit of eight sounds at once apply as they do over HTTP.
• When stdin ends, the command exits 0. When reading it fails, the command exits 1. Claudio does not reconnect: run it under a loop or a service if the source can drop.

There is no token on this path. Whoever can write to the source can play sounds, so protect the source.

claudio soundpack

Manages soundpacks.

claudio soundpack [command]

soundpack init

Creates a JSON soundpack template with all known mapping keys.

claudio soundpack init <name> [flags]

Flags:

Examples:

claudio soundpack init my-pack
claudio soundpack init my-pack --dir ./soundpacks
claudio soundpack init my-pack --from-platform

soundpack list

Lists embedded, XDG, and config-discovered soundpacks with their type, sound count, and path.

claudio soundpack list

The embedded packs are windows, wsl, darwin, and linux.

soundpack validate

Validates a JSON file or directory soundpack and prints coverage.

claudio soundpack validate <path>

Validation checks JSON shape, missing referenced files, known-key coverage, and supported extensions. WAV, MP3, and AIFF are supported. Broken references and unsafe paths (absolute, or containing ..) cause a non-zero exit. Empty mappings are informational.

soundpack audit

Decodes every sound in a JSON file or directory soundpack and reports what a listener would notice.

claudio soundpack audit <path> [flags]

Flags:

Default duration limits: loading 1s, success 1.5s, default 1.5s, error 2s, interactive 2.5s, completion 3s, system 6s.

Warnings: too-long, too-loud, too-quiet, peak-over-ceiling, clipping, leading-silence, trailing-silence. Errors: undecodable, silent. Notes, which never fail an audit: peak-limited, duplicate, sample-rate, unreferenced.

For a JSON pack, audit covers every file the manifest references, regardless of extension, and any unreferenced supported audio in the same directories. Mapped content the playback decoders cannot read, such as Ogg Vorbis, is an undecodable error and fails the audit even without --strict. See Auditing And Mastering for what each column and rule means.

soundpack master

Writes a mastered copy of a soundpack that passes soundpack audit.

claudio soundpack master <path> --out <dir> [flags]

Flags:

Each sound is trimmed of silence, cut to its category’s duration limit with a fade, and brought to the loudness target. Output is 48 kHz 16-bit WAV. A directory pack keeps its layout; a JSON pack becomes <out>/soundpack.json with its sounds under <out>/sounds/. The source is never modified.

soundpack synth

Renders original sounds from a JSON recipe.

claudio soundpack synth <recipe.json> --out <dir>

Writes <out>/synth/<sound>.wav for every sound in the recipe and <out>/soundpack.json, a JSON soundpack mapping the recipe’s keys to those files. Master the result to get a pack at a consistent level. The recipe format is described in Synthesizing Sounds. A recipe with a setting synth does not know, a mapping to a sound that is not defined, or a sound no mapping uses is rejected.

soundpack search

Lists published soundpacks.

claudio soundpack search [words...] [--json]

Queries GitHub for repositories tagged with the topic claudio-soundpack, most starred first, and prints each with the soundpack add command that installs it. Extra words narrow the search. This is the only command that contacts a server on its own. Set GITHUB_TOKEN to raise GitHub’s rate limit.

soundpack install

Copies a local JSON file or directory into the XDG data directory and updates soundpack_paths.

claudio soundpack install <path> [flags]

Flags:

JSON files and their referenced audio files install under <XDG_DATA_HOME>/claudio/soundpacks/<name>/, with the installed manifest at soundpack.json. Directories install to <XDG_DATA_HOME>/claudio/soundpacks/<name>/.

soundpack use

Switches the active soundpack by name.

claudio soundpack use <name>
claudio soundpack use windows

This sets default_soundpack. The name must appear in claudio soundpack list.

soundpack add

Clones a git-backed soundpack into <XDG data home>/claudio/soundpack-repos/<name>/ and adds it to soundpack_paths. Requires git on PATH.

claudio soundpack add <git-url> [flags]

Flags:

GitHub shorthand is accepted:

claudio soundpack add gh:owner/repo --name my-pack --default

soundpack update

Updates managed git soundpacks.

claudio soundpack update <name>
claudio soundpack update --all

Flags:

soundpack remove

Removes a managed git soundpack.

claudio soundpack remove <name>

Flags:

soundpack status

Shows managed git soundpack status.

claudio soundpack status
claudio soundpack status <name>

claudio analyze

Reads the tracking database. Both subcommands fail if tracking is disabled.

claudio analyze usage [flags]
claudio analyze missing [flags]

missing lists fallback-chain candidates that were requested but not found, most requested first. usage lists the sounds that actually played.

Shared flags:

usage also supports:

Examples:

claudio analyze usage --show-summary --show-chains
claudio analyze usage --tool Bash --preset today
claudio analyze missing --preset all-time --limit 50
claudio analyze missing --category error

claudio completion

Generates a shell completion script for Bash, Fish, PowerShell, or Zsh.

claudio completion bash
claudio completion fish
claudio completion powershell
claudio completion zsh

Exit Codes

Subcommand failures return exit code 1.

In hook mode, Claudio exits 1 before playback for an unparseable payload, an out-of-range CLAUDIO_VOLUME or --volume, and an audio backend that cannot be resolved. A config file is never fatal: a missing or empty one means defaults, and one that cannot be parsed or fails validation prints a single Warning: line and Claudio continues with defaults. Once the payload is accepted, missing sounds and playback errors are only logged.

See Also

• Installation
• Configuration
• Soundpacks
• Troubleshooting