Skip to content

Peon Ping for Claude Code audio notifications

  • Date: 2026-03-31
  • Status: Accepted
  • Tags: tooling workflow

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 use
  • use_sound_effects_device: true — routes audio to macOS Sound Effects device so it doesn't interrupt music or calls
  • suppress_sound_when_tab_focused: true — only plays audio for background tabs, reducing noise when actively watching a session
  • pack_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_focused eliminates 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)
  • osascript calls 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.