Game character voice lines when your AI coding agent needs attention.

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 from Warcraft, StarCraft, Portal, Zelda, and more — works with Claude Code, Codex, Cursor, OpenCode, Kilo CLI, Kiro, Windsurf, and Google Antigravity.

See it in action → peonping.com

brew install PeonPing/tap/peon-ping

Then run peon-ping-setup to register hooks and download sound packs. macOS and Linux.

curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.ps1" -UseBasicParsing | Invoke-Expression

Installs 10 curated English packs by default. 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,glados,... — 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:

curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash -s -- --all
curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash -s -- --packs=peon,glados
curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash -s -- --local

If a global install exists and you install local (or vice versa), the installer prompts you to remove the existing one to avoid conflicts.

git clone https://github.com/PeonPing/peon-ping.git
cd peon-ping
./install.sh

Plus Terminal tab titles (● project: done) and desktop notifications when your terminal isn't focused.

peon-ping implements the Coding Event Sound Pack Specification (CESP) — an open standard for coding event sounds that any agentic IDE can adopt.

Need to mute sounds and notifications during a meeting or pairing session? Two options:

Other CLI commands:

peon pause                # Mute sounds
peon resume               # Unmute sounds
peon status               # Check if paused or active
peon packs list           # List installed sound packs
peon packs use <name>     # Switch to a specific pack
peon packs next           # Cycle to the next pack
peon packs remove <p1,p2> # Remove specific packs
peon notifications on     # Enable desktop notifications
peon notifications off    # Disable desktop notifications
peon preview              # Play all sounds from session.start
peon preview <category>   # Play all sounds from a specific category
peon preview --list       # List all categories in the active pack
peon mobile ntfy <topic>  # Set up phone notifications (free)
peon mobile off           # Disable phone notifications
peon mobile test          # Send a test notification
peon relay --daemon       # Start audio relay (for SSH/devcontainer)
peon relay --stop         # Stop background relay

Available CESP categories for peon preview: session.start, task.acknowledge, task.complete, task.error, input.required, resource.limit, user.spam.

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.

peon-ping installs a /peon-ping-toggle slash command in Claude Code. 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.5,
  "categories": {
    "session.start": true,
    "task.acknowledge": true,
    "task.complete": true,
    "task.error": true,
    "input.required": true,
    "resource.limit": true,
    "user.spam": true
  }
}

• volume: 0.0–1.0 (quiet enough for the office)
• desktop_notifications: true/false — toggle desktop notification popups independently from sounds (default: true)
• 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)
• pack_rotation: Array of pack names (e.g. ["peon", "sc_kerrigan", "peasant"]). Each session randomly gets one pack from the list and keeps it for the whole session. Leave empty [] to use active_pack instead.

peon-ping works with any agentic IDE that supports hooks. Adapters translate IDE-specific events to the CESP standard.

A native TypeScript plugin for OpenCode with full CESP v1.0 conformance.

Quick install:

curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/adapters/opencode.sh | bash

The installer copies peon-ping.ts to ~/.config/opencode/plugins/ and creates a config at ~/.config/opencode/peon-ping/config.json. Packs are stored at the shared CESP path (~/.openpeon/packs/).

Features:

• Sound playback via afplay (macOS), pw-play/paplay/ffplay (Linux) — same priority chain as the shell hook
• CESP event mapping — session.created / session.idle / session.error / permission.asked / rapid prompt detection all map to standard CESP categories
• Desktop notifications — rich notifications via terminal-notifier when available (subtitle, per-project grouping), with osascript fallback. Fires only when the terminal is not focused.
• Terminal focus detection — checks if your terminal app (Terminal, iTerm2, Warp, Alacritty, kitty, WezTerm, ghostty, Hyper) is frontmost via AppleScript before sending notifications
• Tab titles — updates the terminal tab to show task status (● project: working... / ✓ project: done / ✗ project: error)
• Pack switching — reads active_pack from config, loads the pack's openpeon.json manifest at runtime
• No-repeat logic — avoids playing the same sound twice in a row per category
• Spam detection — detects 3+ rapid prompts within 10 seconds, triggers user.spam voice lines

Tip: Install terminal-notifier (brew install terminal-notifier) for richer notifications with subtitle and grouping support.

bash <(curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/adapters/opencode/setup-icon.sh)

bash ~/.claude/hooks/peon-ping/adapters/opencode/setup-icon.sh

A native TypeScript plugin for Kilo CLI with full CESP v1.0 conformance. Kilo CLI is a fork of OpenCode and uses the same plugin system — this installer downloads the OpenCode plugin and patches it for Kilo.

Quick install:

curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/adapters/kilo.sh | bash

The installer copies peon-ping.ts to ~/.config/kilo/plugins/ and creates a config at ~/.config/kilo/peon-ping/config.json. Packs are stored at the shared CESP path (~/.openpeon/packs/).

Features: Same as the OpenCode adapter — sound playback, CESP event mapping, desktop notifications, terminal focus detection, tab titles, pack switching, no-repeat logic, and spam detection.

Add to ~/.codeium/windsurf/hooks.json (user-level) or .windsurf/hooks.json (workspace-level):

{
  "hooks": {
    "post_cascade_response": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh post_cascade_response", "show_output": false }
    ],
    "pre_user_prompt": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh pre_user_prompt", "show_output": false }
    ],
    "post_write_code": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh post_write_code", "show_output": false }
    ],
    "post_run_command": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh post_run_command", "show_output": false }
    ]
  }
}

Create ~/.kiro/agents/peon-ping.json:

{
  "hooks": {
    "agentSpawn": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/kiro.sh" }
    ],
    "userPromptSubmit": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/kiro.sh" }
    ],
    "stop": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/kiro.sh" }
    ]
  }
}

preToolUse/postToolUse are intentionally excluded — they fire on every tool call and would be extremely noisy.

Coding on a remote server or inside a container? peon-ping auto-detects SSH sessions, devcontainers, and Codespaces, then routes audio and notifications through a lightweight relay running on your local machine.

1. On your local machine, start the relay:

   peon relay --daemon

2. SSH with port forwarding:

   ssh -R 19998:localhost:19998 your-server

3. Install peon-ping on the remote — it auto-detects the SSH session and sends audio requests back through the forwarded port to your local relay.

That's it. Sounds play on your laptop, not the remote server.

No port forwarding needed — peon-ping auto-detects REMOTE_CONTAINERS and CODESPACES environment variables and routes audio to host.docker.internal:19998. Just run peon relay --daemon on your host machine.

peon relay                # Start relay in foreground
peon relay --daemon       # Start in background
peon relay --stop         # Stop background relay
peon relay --status       # Check if relay is running
peon relay --port=12345   # Custom port (default: 19998)
peon relay --bind=0.0.0.0 # Listen on all interfaces (less secure)

Environment variables: PEON_RELAY_PORT, PEON_RELAY_HOST, PEON_RELAY_BIND.

If peon-ping detects an SSH or container session but can't reach the relay, it prints setup instructions on SessionStart.

Get push notifications on your phone when tasks finish or need attention — useful when you're away from your desk.

1. Install the ntfy app on your phone
2. Subscribe to a unique topic in the app (e.g. my-peon-notifications)
3. Run:

   peon mobile ntfy my-peon-notifications

Also supports Pushover and Telegram:

peon mobile pushover <user_key> <app_token>
peon mobile telegram <bot_token> <chat_id>

peon mobile on            # Enable mobile notifications
peon mobile off           # Disable mobile notifications
peon mobile status        # Show current config
peon mobile test          # Send a test notification

Mobile notifications fire on every event regardless of window focus — they're independent from desktop notifications and sounds.

43+ packs across Warcraft, StarCraft, Red Alert, Portal, Zelda, Dota 2, Helldivers 2, Elder Scrolls, and more. The default install includes 10 curated English packs:

Browse all packs with audio previews → openpeon.com/packs

Install all with --all, or switch packs anytime:

peon packs use glados             # switch to a specific pack
peon packs next                   # cycle to the next pack
peon packs list                   # list all installed packs

Want to add your own pack? See the full guide at openpeon.com/create or CONTRIBUTING.md.

macOS/Linux:

bash "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/hooks/peon-ping/uninstall.sh        # global
bash .claude/hooks/peon-ping/uninstall.sh           # project-local

Windows (PowerShell):

# Standard uninstall (prompts before deleting sounds)
powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.claude\hooks\peon-ping\uninstall.ps1"

# Keep sound packs (removes everything else)
powershell -ExecutionPolicy Bypass -File "$env:USERPROFILE\.claude\hooks\peon-ping\uninstall.ps1" -KeepSounds

• macOS (uses afplay and AppleScript), Windows (native PowerShell or WSL2, uses PowerShell MediaPlayer and WinForms), or Linux (uses pw-play/paplay/ffplay/mpv/aplay and notify-send)
• Claude Code with hooks support
• python3 (not required for native Windows)
• For SSH/remote: curl on the remote host

peon.sh is a Claude Code hook registered for SessionStart, UserPromptSubmit, Stop, Notification, and PermissionRequest events. On each event it maps to a CESP sound category, picks a random voice line (avoiding repeats), plays it via afplay (macOS), PowerShell MediaPlayer (WSL2), or paplay/ffplay/mpv/aplay (Linux), and updates your Terminal tab title. In SSH sessions, devcontainers, and Codespaces, audio and notification requests are forwarded over HTTP to a relay server (relay.sh) running on your local machine.

Sound packs are downloaded from the OpenPeon registry at install time. The official packs are hosted in PeonPing/og-packs. Sound files are property of their respective publishers (Blizzard, Valve, EA, etc.) and are distributed under fair use for personal notification purposes.

• @peonping on X — updates and announcements
• peonping.com — landing page
• openpeon.com — CESP spec, pack browser, creation guide
• OpenPeon registry — pack registry (GitHub Pages)
• og-packs — official sound packs
• License (MIT)