Peon Ping for Claude Code audio notifications¶
- Date: 2026-03-31
- Status: Accepted
- Tags:
toolingworkflow
Context¶
Claude Code sessions run in terminal tabs that are often not in the foreground. Without audio or visual cues, users miss when the agent finishes a response, hits an error, or needs input — leading to wasted time polling tabs manually. This is especially painful with multiple concurrent sessions (e.g., Fleet Commander teams running in parallel).
We needed a notification system that:
- Plays contextual audio cues mapped to agent lifecycle events
- Supports multiple voice packs for variety and personalization
- Manages terminal tab titles for at-a-glance session status
- Sends desktop notifications when the terminal is not focused
- Is configurable per-project, per-directory, and per-session
Decision¶
We will use Peon Ping, an open source Claude Code hook that provides audio notifications, tab title management, and desktop notifications via the Claude Event Sound Protocol (CESP).
Installation: The hook lives at ~/.claude/hooks/peon-ping/ and is
wired into settings.json via PostToolUse, Notification, and Stop
hook events.
Voice packs: Community-contributed sound packs stored at
~/.claude/hooks/peon-ping/packs/. Packs rotate per-session (random or
round-robin) and can be pinned to directories via path_rules.
Key configuration choices for this setup:
volume: 0.3— low enough for background useuse_sound_effects_device: true— routes audio to macOS Sound Effects device so it doesn't interrupt music or callssuppress_sound_when_tab_focused: true— only plays audio for background tabs, reducing noise when actively watching a sessionpack_rotation_mode: "random"with 10 packs in rotation for variety
Companion skills: /peon-ping-config, /peon-ping-toggle,
/peon-ping-use, and /peon-ping-log provide conversational control
over settings, muting, pack selection, and exercise tracking.
Alternatives Considered¶
| Option | Why Rejected |
|---|---|
macOS terminal bell (\a) |
Single tone, no category distinction, no tab title management |
| Custom notification script | Peon Ping already solves this comprehensively with community packs |
| Desktop-only notifications (no sound) | Easy to miss in notification center; audio is more immediate |
| ntfy.sh / Pushover | Adds external service dependency for something that works locally |
Consequences¶
Positive:
- Immediate awareness of agent state changes across multiple terminal tabs
- Tab titles show session status without switching focus
- Voice pack variety prevents notification fatigue
suppress_sound_when_tab_focusedeliminates noise for the active session- Sound Effects device routing keeps notifications separate from media audio
Negative / Trade-offs:
- Sound packs consume disk space (~50–200 MB total across all packs)
osascriptcalls for focus detection add minor latency on macOS- Warp terminal reports process name as
"stable"— required a patch to the focus detection case statement
Ongoing obligations:
- Update packs when new versions are released
- Review config when new CESP categories are added upstream
- Maintain the
"stable"process name workaround if Warp changes its reported name
ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.