Audio Feedback

Audio Feedback — Accessible Audio Cues for Claude Code

The audio-feedback plugin provides non-speech audio cues for Claude Code hook events, supporting awareness of Claude's activity without needing to watch the terminal. Short synth sounds fire on response complete, notifications, context compaction, user input, tool calls, subagent completion, session start, and pre-compact. Each event maps to a configurable sound (or off) and is organised by theme. Independent of the tts plugin (purely non-speech).

First Step

When invoked with no arguments, the FIRST action must be a single AskUserQuestion tool call (no preamble):

"What would you like to do with audio-feedback?"

Set header: "Action" and offer: config, sounds, test, help.

If the user's message already includes a subcommand, skip the AUQ and jump into the matching workflow.

Helper Commands

• audio-feedback-config [KEY=VALUE ...] — view or update config

Invoke as a bare command — bin/ is on PATH automatically.

Configuration Reference

Global config: ~/.claude/.audio-feedback-config

Core

Set any event to off to silence it. Set ENABLED=false to silence everything.

Subtype-specific sounds (e.g. notification-permission.wav, post-tool-use-observe.wav) are auto-resolved from the theme directory when present, falling back to the generic sound above.

Bundled Sounds — Default Theme

Lo-fi minimal aesthetic, 0.5s reverb tail, normalised to 0dB peak, mono 44.1 kHz.

Generic event sounds

Subtype-aware variants

The hook inspects the JSON payload and, when a subtype-specific WAV exists, prefers it over the generic sound. Lets the user distinguish kinds of events by ear — core to the accessibility purpose of the plugin.

Tool-group mapping (so one file serves a family of tools):

Any WAV file not listed is a silent no-op if missing from the active theme — themes don't need to ship a complete set.

Workflow: CONFIG

Two modes:

• No args — run audio-feedback-config to show current config. Pass output through.
• With KEY=VALUE — run audio-feedback-config KEY=VALUE [...] to update. Validates sound names against bundled files.

Workflow: SOUNDS

Run audio-feedback-config (no args) — its footer lists sounds in the active theme and all available themes.

Workflow: TEST

Play each configured sound that isn't off in sequence so the user can hear them. Resolves the active theme directory so the test works regardless of THEME.

cfg=$(audio-feedback-config 2>/dev/null)
plugin_root=$(dirname "$(dirname "$(readlink -f "$(which audio-feedback-config)")")")
theme=$(printf '%s' "$cfg" | awk -F= '/^  THEME=/{print $2}')
sounds_dir="$plugin_root/sound-theme/${theme:-default}/sounds"

for key in STOP_SOUND NOTIFICATION_SOUND PRE_COMPACT_SOUND USER_PROMPT_SOUND \
           SESSION_START_SOUND SUBAGENT_STOP_SOUND PRE_TOOL_USE_SOUND POST_TOOL_USE_SOUND; do
    sound=$(printf '%s' "$cfg" | awk -F= -v k="  $key" '$1==k{print $2}')
    [ -z "$sound" ] || [ "$sound" = "off" ] && { echo "$key: $sound"; continue; }
    echo "$key: $sound"
    paplay "$sounds_dir/${sound}.wav" 2>/dev/null || echo "  [missing: $sounds_dir/${sound}.wav]"
done

Show which event→sound mappings played and which were off or missing.

Workflow: HELP

Print the subcommand grammar, config reference table, and bundled sounds table inline. No helper script needed.

Subcommand Grammar

/audio-feedback                     → interactive (AUQ first)
/audio-feedback config [KEY=VALUE]  → view or update config
/audio-feedback sounds              → list available sounds
/audio-feedback test                → play all active sounds in sequence
/audio-feedback help                → grammar + config + sounds reference

Important Notes

• Coexistence with tts plugin: If tts is also installed with CHIME_ENABLED=true, both plugins fire on Stop — double chime. Disable one: either /tts config CHIME_ENABLED=false or /audio-feedback config STOP_SOUND=off.
• PreToolUse and PostToolUse default to off because they fire on EVERY tool call (high frequency, can be annoying during heavy tool use).
• When a hook's JSON payload carries agent_id (i.e. the tool call was made on behalf of a subagent), the sound's <name>-subagent.wav background variant (extra reverb + low-pass, "heard from another room") plays instead of the plain sound, if SUBAGENT_ACCENT=true (default).
• Hooks are non-blocking: the event sound runs in a detached background process, so the hook script returns in ~50ms regardless of paplay latency.
• Requires PipeWire (paplay). The optional playback daemon (af-soundd) needs uv (which supplies sounddevice/soundfile/numpy via PEP 723) and collapses concurrent playback into one process / one PipeWire client; without uv, each event uses paplay. Subtype resolution needs jq.