内容摘录
peon-ping
<div align="center">
**English** | 中文
!macOS !WSL2 !Linux !Windows !SSH
!License
!Claude Code !Gemini CLI !GitHub Copilot !Codex !Cursor !OpenCode !Kilo CLI !Kiro !Windsurf !Antigravity !OpenClaw
**Game character voice lines + visual overlay notifications when your AI coding agent needs attention — or let the agent pick its own sound via MCP.**
AI coding agents don't notify you when they finish or need permission. You tab away, lose focus, and waste 15 minutes getting back into flow. peon-ping fixes this with voice lines and bold on-screen banners from Warcraft, StarCraft, Portal, Zelda, and more — works with **Claude Code**, **GitHub Copilot**, **Codex**, **Cursor**, **OpenCode**, **Kilo CLI**, **Kiro**, **Windsurf**, **Google Antigravity**, and any MCP client.
**See it in action** → peonping.com
<video src="docs/public/demo-avatar.mp4" autoplay loop muted playsinline width="400"></video>
</div>
---
Install
What you'll hear
Quick controls
Configuration
Peon Trainer
MCP server
Multi-IDE support
Remote development
Mobile notifications
Sound packs
Uninstall
Requirements
How it works
Links
---
Install
Option 1: Homebrew (recommended)
Then run peon-ping-setup to register hooks and download sound packs. macOS and Linux.
Option 2: Installer script (macOS, Linux, WSL2)
Option 3: Installer for Windows
Installs 5 curated packs by default (Warcraft, StarCraft, Portal). Re-run to update while preserving config/state. Or **pick your packs interactively at peonping.com** and get a custom install command.
Useful installer flags:
--all — install all available packs
--packs=peon,sc_kerrigan,... — install specific packs only
--local — install packs and config into ./.claude/ for the current project (hooks are always registered globally in ~/.claude/settings.json)
--global — explicit global install (same as default)
--init-local-config — create ./.claude/hooks/peon-ping/config.json only
--local does not modify your shell rc files (no global peon alias/completion injection). Hooks are always written to the global ~/.claude/settings.json with absolute paths so they work from any project directory.
Examples:
If a global install exists and you install local (or vice versa), the installer prompts you to remove the existing one to avoid conflicts.
Option 4: Clone and inspect first
What you'll hear
| Event | CESP Category | Examples |
|---|---|---|
| Session starts | session.start | *"Ready to work?"*, *"Yes?"*, *"What you want?"* |
| Task finishes | task.complete | *"Work, work."*, *"I can do that."*, *"Okie dokie."* |
| Permission needed | input.required | *"Something need doing?"*, *"Hmm?"*, *"What you want?"* |
| Tool or command error | task.error | *"I can't do that."*, *"Son of a bitch!"* |
| Agent acknowledged task | task.acknowledge | *"I read you."*, *"On it."* *(disabled by default)* |
| Rate or token limit hit | resource.limit | *"Zug zug."* *(pack dependent)* |
| Rapid prompts (3+ in 10s) | user.spam | *"Me busy, leave me alone!"* |
Plus **large overlay banners** on every screen (macOS/WSL) and terminal tab titles (● project: done) — you'll know something happened even if you're in another app.
peon-ping implements the Coding Event Sound Pack Specification (CESP) — an open standard for coding event sounds that any agentic IDE can adopt.
Quick controls
Need to mute sounds and notifications during a meeting or pairing session? Two options:
| Method | Command | When |
|---|---|---|
| **Slash command** | /peon-ping-toggle | While working in Claude Code |
| **CLI** | peon toggle | From any terminal tab |
Other CLI commands:
Available CESP categories for peon preview: session.start, task.acknowledge, task.complete, task.error, input.required, resource.limit, user.spam. (Extended categories session.end and task.progress are defined in the CESP spec and supported by pack manifests, but not currently triggered by built-in hook events.)
Tab completion is supported — type peon packs use <TAB> to see available pack names.
Pausing mutes sounds and desktop notifications instantly. Persists across sessions until you resume. Tab titles remain active when paused.
Configuration
peon-ping installs two slash commands in Claude Code:
/peon-ping-toggle — mute/unmute sounds
/peon-ping-config — change any setting (volume, packs, categories, etc.)
You can also just ask Claude to change settings for you — e.g. "enable round-robin pack rotation", "set volume to 0.3", or "add glados to my pack rotation". No need to edit config files manually.
Config location depends on install mode:
Global install: $CLAUDE_CONFIG_DIR/hooks/peon-ping/config.json (default ~/.claude/hooks/peon-ping/config.json)
Local install: ./.claude/hooks/peon-ping/config.json
**volume**: 0.0–1.0 (quiet enough for the office)
**desktop_notifications**: true/false — toggle desktop notification popups independently from sounds (default: true)
**notification_style**: "overlay" or "standard" — controls how desktop notifications appear (default: "overlay")
**overlay**: large, visible banners — JXA Cocoa overlay on macOS, Windows Forms popup on WSL
**standard**: system notifications — osascript / terminal-notifier on macOS, Windows toast on WSL
**categories**: Toggle individual CESP sound categories on/off (e.g. "session.start": false to disable greeting sounds)
**annoyed_threshold / annoyed_window_seconds**: How many prompts in N seconds triggers the user.spam easter egg
**silent_window_seconds**: Suppress task.complete sounds and notifications for tasks shorter than N seconds. (e.g. 10 to only hear sounds for tasks that take longer than 10 seconds)
**suppress_subagent_complete** (boolean, default: false): Suppress task.complete sounds and notifications when a sub-agent session finishes. When Claude Code's Task tool dispatches parallel sub-agents, each one fires a completion sound — set this to true to hear only the parent session's completion sound.
**default_pack**: The fallback pack used when no more specific rule appli…