$ show PeonPing/peon-ping
Peon-ping is a cross-platform sound notification system for AI coding agents (Claude Code, Cursor, Codex, OpenCode, etc.). It intercepts agent lifecycle events (session start/stop, task complete, error, permission requests) via shell hooks and IDE-specific adapters, translates them into a standardized CESP (Coding Event Sound Pack Specification) JSON format, and plays themed sound effects with optional desktop notifications and TTS speech. The architecture is event-driven and hook-based: each IDE has a thin adapter script that pipes CESP events to a core hook script (`peon.sh` on Unix, `peon.ps1` on Windows) which performs sound selection from configurable packs, asynchronous audio playback via platform-native players, state persistence (atomic file I/O), and notification dispatch (macOS overlay, system notifications, relay for remote/SSH sessions). Additional features include a trainer (exercise reminders), an MCP server for agent-controlled sound playback, and a sound pack registry with 160+ packs. The codebase applies an adapter pattern, atomic state I/O, structured debug logging (ADR-002), and a path-rules-based pack resolution system. It is heavily tested with BATS (Unix) and Pester (Windows) suites, managed via an agent-based gitban workflow with sprint planning and code reviews. Dependencies include Python3, audio players (afplay, ffplay, pw-play, PowerShell MediaPlayer), and platform-specific notification tools. Key concerns are the monolithic hook scripts (single ~5000-line files per platform), cross-platform code duplication, and the maintenance burden of 20+ IDE adapters.
The LLM identified 5 files worth highlighting for reuse:
Provides isolated BATS test environments with mock binaries (afplay, osascript, curl, etc.), temporary directories, and helper functions (setup_test_env, enable_debug_logging). Self-contained and reusable for any shell script testing project requiring hermetic test execution.
Contains platform-shared PowerShell helper functions: Read-StateWithRetry and Write-StateAtomic for safe state file I/O (temp+rename, orphan cleanup), Get-PeonConfigRaw with locale decimal fix and BOM stripping, and Set-PeonConfig for culture-safe JSON writing. Extracts common Windows installer patterns reusable across PowerShell tools.
Implements an animated macOS notification overlay using JXA with ObjC bridge. Supports multi-screen positioning, configurable slot stacking, click-to-focus via ProcessIdentifier, event-driven dismissal via distributed notifications, and auto-dismiss timer. Self-contained and adaptable for any macOS notification system.
Downloads and caches sound packs from a remote registry with HTTP checksum verification, ETag caching, progress bars, and fallback to git clone. Supports language filtering and metadata extraction from pack manifests. A reusable shell-based content downloader with validation and caching.
Exposes sound playback as a Model Context Protocol server with a play_sound tool, sound catalog resource, and prompt templates for agent-to-agent handoff. Demonstrates a clean MCP server implementation pattern for agent-controlled automation using Node.js stdio transport.