Journal

2026-02-26

2026-02-26

Signal

Audio feedback transforms a headless CLI agent from a black box into a system you can monitor by ear : the first day projects/peon-notify/_index shipped revealed that sound categorization matters more than sound volume.

Evidence

  • Project: projects/peon-notify/_index : v0.1.0 initial release shipped today
  • Decision: Warcraft III Peon voice lines chosen over generic beeps because the 15 sound categories map to semantically distinct Claude Code event types (tool failure vs. system error vs. rate limit hit)
  • Architecture: Config-driven from day one via peon.json : no code changes required to customize behavior, only config edits
  • Cross-platform: macOS/Linux/WSL all supported via a queue-and-drain loop with a cooldown system to prevent sound spam

So What (Why Should You Care)

When you run Claude Code agents overnight or in background sessions, you lose the visual feedback loop. You can’t watch a terminal for eight hours. projects/peon-notify/_index solves this by mapping 15 distinct event types : from tool failures to API rate limits to system errors : to audio cues you can recognize without looking at a screen.

The design lesson here is broader than notifications. Any headless automation system that runs unattended benefits from an out-of-band signal channel : one that doesn’t require the operator to be watching the right screen at the right moment. Sound is the obvious choice because it’s ambient: it reaches you regardless of what application is in focus.

The choice of Warcraft III Peon voice lines over generic beeps isn’t whimsy. It’s a deliberate UX decision about signal distinctiveness. Generic beeps are undifferentiated : you know something happened but not what. Peon voice lines are semantically loaded (veteran players recognize the specific character’s personality as frustrated, overworked, or complaining) and memorable. After a few days of use, you build an auditory vocabulary: “that sound means a tool timed out,” “that sound means the API rate limit was hit.” Generic beeps don’t build that vocabulary because they’re not distinct enough to differentiate.

The config-driven architecture deserves emphasis. The decision to make every behavior configurable via peon.json from day one : rather than hardcoding sound assignments and then adding config later : reflects a principle that’s easy to preach and hard to follow: future customization is always cheaper to support if the architecture assumes it from the start. Every hardcoded value that becomes a config option requires a refactor; every config option that becomes hardcoded requires a revert.

The cooldown system is the third architectural decision worth noting. Without it, a tool that calls 20 file writes in two seconds would produce 20 sounds. With it, rapid-fire events are batched into a single sound cue per window. This matters because a system that produces too many sounds becomes ignored : the audio equivalent of alert fatigue.

The health check script (peon-health.sh) and idempotent installer with dry-run support are the operational details that separate a tool that works in one environment from a tool that’s deployable. An idempotent installer can be run repeatedly without causing problems : you don’t need to track whether you already installed it. A dry-run mode lets you verify what the installer will do before it does anything. These features are invisible until you need to reinstall on a new machine or diagnose a broken installation : at which point they’re the difference between a 2-minute fix and a 30-minute investigation.

The cross-platform support (macOS/Linux/WSL) also reflects a deliberate design choice rather than an afterthought. Most automation tools start macOS-only and add Linux support later when they realize collaborators or CI environments need it. Starting with all three platforms means the queue-and-drain architecture was designed with platform-specific audio playback differences in mind from the first commit rather than patched in after the fact.

What’s Next

  • Add code quality pipeline to PeonNotify : lint and AI review on file writes
  • Add documentation generation capability
  • Validate cooldown system behavior under high-frequency event bursts

Log

  • Built projects/peon-notify/_index v0.1.0 audio notification system for Claude Code CLI
  • Implemented event dispatch with 15 sound categories mapping to Warcraft III Peon voice lines
  • Built cross-platform audio playback (macOS/Linux/WSL) with queue and drain loop
  • Added cooldown system to prevent sound spam during rapid tool invocations
  • Designed config-driven behavior via peon.json : zero code changes to customize
  • Shipped health check script (peon-health.sh) for diagnostics
  • Built idempotent installer with dry-run support