Peon Ping — AI Agent Voice Notifications
Add Warcraft-style voice lines and bold on-screen banners to Claude Code, Codex, Cursor, and any AI agent. Stop babysitting your terminal.
Evidence shows: install scripts modify user config (e.g., ~/.claude/settings.json) and download sound packs, but do not clearly state permission scope or least privilege. User confirmation: interactive wizard exists, but not all modifications require explicit confirmation. Data flow transparency: documentation describes events and notifications, but not detailed data flow or uploads. Sensitive data handling: no mention of handling sensitive data, but may read session info. Dependency security: no dependency list or security audit. External effects: modifies system settings and plays sounds, but impact scope not stated. Rollback: uninstall script provided, but rollback mechanism not described. Source attribution: sound pack sources and verification not clearly stated.
Evidence shows: README and tests are mostly consistent, but some features (e.g., Windows support) are marked as partial, indicating inconsistency. Dependency availability: relies on external services (Homebrew, GitHub) and system components, but no availability guarantees. Failure messages: some debug commands documented, but error handling not detailed.
Evidence shows: multiple IDEs and platforms explicitly listed, broad scenario coverage. Capability boundaries: supported events and features documented, but limitations not explicit. Trigger precision: detailed configuration options and event categories, but trigger implementation not described. Environment fit: multiple installation methods and config options, but not all environments detailed.
Evidence shows: README well-structured with install, config, usage sections. Install notes detailed with multiple methods. Naming stability: commands and config keys consistent. Examples and FAQ: examples and some FAQ provided, but not comprehensive. Known limitations: Windows partial support mentioned, but not exhaustive. License: MIT clear. Versioning/changelog: no explicit version or changelog. Maintenance responsibility: maintainers or contribution guidelines not stated.
Evidence shows: output (sounds and notifications) designed to be intuitive. Marginal value: unique feature (game sound notifications), but may be limited for some users. Cost-benefit: low install/use cost, but requires downloading sound packs and configuration.
Evidence shows: some claims supported by tests (e.g., OpenCode adapter tests), but not all claims verified. Cross-source corroboration: no multiple sources. Fact/inference separation: not clearly distinguished.
- Install scripts modify user config and download external content; review before executing.
- Sound pack sources not clearly verified, potential security risk.
- Some features (e.g., advanced Windows commands) not fully implemented; documentation may overstate.
What does this agent do, and when should you use it?
peon-ping is an open-source tool that provides game-character voice notifications and visual overlay banners for AI coding agents. When an agent finishes, requests input, errors, or hits rate limits, it plays voice lines from Warcraft, StarCraft, Portal, Zelda, and more, and shows large overlay banners on all screens (macOS/WSL/MSYS2), plus updates terminal tab titles. It implements the Coding Event Sound Pack Specification (CESP) and supports integrations via adapters for Claude Code, Amp, GitHub Copilot, Codex, Cursor, OpenCode, Kilo CLI, Kiro, Kimi Code, Windsurf, Google Antigravity, Rovo Dev CLI, DeepAgents, Qwen Code, iFlow CLI, Trae, Kiro IDE, ECA, and more. It includes an MCP server so any MCP-compatible AI agent can directly call a play_sound tool. Configuration is extensive: volume, per-category toggles, notification styles, themes, pack rotation, path/IDE rules, Focus/Do Not Disturb detection, meeting detection, mobile push via ntfy, and a CLI-based fitness trainer.
peon-ping installs hooks or adapters that translate IDE events (session.start, task.complete, input.required, task.error, resource.limit, user.spam) into sounds and notifications. The core is a shell script (peon.sh/peon.ps1) that parses event payloads, reads config at ~/.claude/hooks/peon-ping/config.json, selects a sound pack via a six-layer priority hierarchy (session_override > path_rules > ide_rules > pack_rotation > default_pack > hardcoded 'peon'), and plays audio using afplay (macOS), pw-play/paplay/ffplay (Linux), or MediaPlayer/SoundPlayer (Windows). Desktop notifications are rendered as large clickable overlays (JXA Cocoa on macOS, Windows Forms on WSL/MSYS2) that can focus the originating terminal, or as standard system notifications. It provides a CLI (peon) for managing packs, volume, notifications, rotation, path bindings, and excluded directories. The MCP server (mcp/peon-mcp.js) exposes a play_sound tool and catalog resources.
- A developer using Claude Code wants to hear 'Work complete' when a long-running task finishes, so they can switch contexts without watching the terminal.
- A developer using Codex wants a prominent visual alert when the agent requires permission, ensuring they don't miss input requests.
- A multi-project developer wants different sound packs per project or IDE, configured via path_rules or ide_rules.
- A remote developer over SSH/devcontainer uses peon relay to hear audio locally.
- A developer wants mobile push notifications via ntfy to get alerts when away from the computer.
- A developer wants to be reminded to exercise during coding sessions using the built-in peon trainer feature.
What are this agent's strengths and limitations?
- Extensive IDE support including Claude Code, Codex, Cursor, Copilot, and more via adapters.
- Highly configurable: pack rotation, path/IDE bindings, Focus detection, meeting detection, notification styles and themes.
- Built-in MCP server allowing AI agents to autonomously play sounds, providing more flexible interaction.
- Follows the open CESP specification; sound packs can be fetched from a registry, enhancing portability.
- Optimized for terminal-based workflows; GUI IDE support requires additional adapter setup and may not be seamless.
- Windows support is incomplete for advanced commands like setup, rotation, preview.
- Depends on external tools like ffmpeg (for MP3 on WSL2) and terminal-notifier (standard notifications on macOS), adding install complexity.
- Audio output may require manual tweaking in some environments (e.g., WSL2 older versions), posing compatibility issues.
How do you install or deploy this agent?
Recommended via Homebrew: brew install PeonPing/tap/peon-ping, then run peon-ping-setup to register hooks and download sound packs. Alternatively use the installer script: curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash. Windows users can run the PowerShell installer: Invoke-WebRequest -Uri "https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.ps1" -OutFile ".\install.ps1"; powershell -ExecutionPolicy Bypass -File .\install.ps1. Nix users can run directly: nix run github:PeonPing/peon-ping -- status.
How do you use this agent?
After installation, run peon setup to configure volume, categories, notification theme, and position. Common commands: peon status, peon toggle, peon packs list, peon packs use glados, peon notifications on/off, peon volume 0.7. In Claude Code, use slash commands /peon-ping-toggle and /peon-ping-config. For MCP clients, add the MCP server configuration to enable the play_sound tool.