Logic-to-Sound Feedback for Claude Code
Audio feedback for what your Claude Code agent is doing. The moment Claude finishes, errors out, needs you, completes a long task, or a session starts/ends, it plays a distinct musical motif through macOS system sounds — so you know what happened without watching the terminal.
When something needs your attention (failure / action / alarm / long task), it can also use macOS say to speak which session is calling (see Spoken announcements).
Built on Claude Code's hook mechanism (covering 9 lifecycle events). Pure shell, zero third-party dependencies, zero config (no API key needed).
Design principles
- Instant: classification uses only the event type / keywords — never an LLM/API call. A delayed sound is worse than none: a chime that lands while you're already reading the output just interrupts your judgment.
- Zero config, zero deps: macOS
afplay + /System/Library/Sounds, nothing to install, reuses your existing Claude Code login.
- Never gets in the way: the script always
exit 0, never blocks Claude, and never changes your system volume (only per-playback gain via afplay -v).
Sounds aren't single beeps — afplay -r pitch-shifts one sample into small arpeggios/chords (rising, falling, doorbell, triple buzz…), so they're recognizable and not monotonous.
Sound map (9 categories, by priority)
| Category | Trigger | Motif | Priority |
|---|
| 🚨 api-alarm | StopFailure: API/system error (rate limit, auth failure, overload… language-independent) | Basso, low urgent triple buzz | 100 |
| ❌ failure | Stop reply contains error/failed/exception/denied | Submarine, three descending notes | 80 |
| 🔔 action | permission prompt / MCP dialog / Stop reply is a question (? or "should I…") | Ping, doorbell two-note ×2 | 70 |
| ⏱️ long-tool | a single tool ran ≥ 30s and finished | Glass, high triad | 50 |
| ✅ success | Stop / SubagentStop finished normally | Glass, rising major arpeggio + sustained chord | 30 |
| 🗜️ pre-compact | before context compaction | Morse, rhythmic tick | 20 |
| ▶️ session-start | session start | Bottle, rising two-note | 15 |
| ⏹️ session-end | session end (quit/logout/clear) | Bottle, descending two-note | 15 |
| 💤 idle | Claude idle, waiting for input (off by default, rate-limited when on) | Tink, single soft note | 10 |
Priority: failure/alarm > action > the rest. Loudness rises with priority (important sounds are louder/brighter).
Concurrency & preemption
No more pgrep (which gets falsely suppressed by your music). Coordination goes through a state dir ~/.claude/feedback.state/:
- Tracks only our own playback: playing Spotify / other audio does not suppress our cues.
- Priority preemption: an api-alarm (100) interrupts a playing success chime (30); a success will not interrupt a playing failure sound.
- Cross-session mutual exclusion: multiple Claude windows share one lock (atomic
mkdir) and one "speaker owner" record, so they don't trample each other.
- Stale-resistant: the lock is judged stale by mtime; processes are always validated with
kill -0 + a ps command-name check (so a reused PID can never kill an unrelated process).
Requirements
- macOS (
afplay + /System/Library/Sounds). jq optional (falls back to grep/sed if absent).
- macOS only; Linux (
aplay, no pitch-shift) is not implemented.
Layout (Claude Code plugin)
This repo is itself a marketplace + plugin:
music-feedback/
├── .claude-plugin/
│ └── marketplace.json # marketplace manifest (points to the plugin below)
└── plugins/
└── sound-feedback/
├── .claude-plugin/
│ └── plugin.json # plugin manifest
├── hooks/
│ └── hooks.json # registers the 9 hooks (via ${CLAUDE_PLUGIN_ROOT})
├── scripts/
│ └── feedback.sh # data table + motif playback + concurrency + routing (single script)
└── commands/ # /sound-feedback:demo | :mute | :unmute
Runtime (auto-created): ~/.claude/feedback.state/ (lock + owner record + tool timers), optional ~/.claude/feedback.{off,conf}.
Install
As a plugin (recommended)
One-line install inside Claude Code:
/plugin marketplace add zkwasm/music-feedback
/plugin install sound-feedback@music-feedback
Or from a local path: /plugin marketplace add /path/to/music-feedback.
The plugin's hooks coexist additively with any hooks you already have in settings.json — no conflict. After install they show up in /hooks; apply changes with /reload-plugins (or a new session). Bundled commands: /sound-feedback:demo, :mute, :unmute.
Try locally (without installing)
claude --plugin-dir /path/to/music-feedback/plugins/sound-feedback
