Frequently Asked Questions

What is PeonPing?

PeonPing plays game character voice lines and shows overlay notifications when your AI coding agent needs attention. Instead of tabbing back constantly to check if Claude is done, you hear “Work, work” from the Warcraft Orc Peon (or 165+ other characters) and see a bold banner on every screen.Works with Claude Code, Cursor, OpenCode, GitHub Copilot, Codex, Amp, and other agentic IDEs via adapters.

Which platforms are supported?

macOS — native afplay, JXA Cocoa overlays
Linux — PipeWire, PulseAudio, or ffmpeg backends
Windows — native PowerShell with MediaPlayer and WinForms (no WSL required)
WSL2 — PowerShell audio fallback + Windows toast notifications
MSYS2 / Git Bash — audio via ffplay/mpv or PowerShell fallback
SSH / Devcontainers / Codespaces — audio relay to your local machine

How do I install it?

Homebrew (macOS/Linux, recommended):

brew install PeonPing/tap/peon-ping
peon-ping-setup

curl installer (macOS/Linux/WSL):

curl -fsSL https://peonping.com/install | bash

Windows (PowerShell):

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

See the installation guide for more options.

Do I need WSL on Windows?

No! PeonPing has native PowerShell support. The installer, hook scripts, and all audio playback work on native Windows without WSL.WSL is still supported if you prefer it, but it’s not required.

How do I mute sounds during meetings?

Two ways:In Claude Code:

/peon-ping-toggle

From any terminal:

peon pause

To unmute:

peon resume

Pausing mutes sounds and desktop notifications instantly. Tab titles remain active. The pause state persists across sessions until you resume.

Can I disable desktop notifications but keep sounds?

Yes! Desktop notifications are independent from sounds.

peon notifications off

Sounds will continue playing, but visual popups are suppressed. Mobile notifications (if configured) are unaffected.To re-enable:

peon notifications on

Can I use PeonPing over SSH?

Yes! PeonPing auto-detects SSH sessions and routes audio through a relay server on your local machine.

On your local machine:

peon relay --daemon

SSH with port forwarding:

ssh -R 19998:localhost:19998 your-server

Sounds and notifications play on your laptop, not the remote server. See remote development for details.

How do I switch sound packs?

Switch to a specific pack:

peon packs use glados

Install and switch in one step:

peon packs use --install glados

Cycle to the next pack:

peon packs next

List installed packs:

peon packs list

Browse all available packs with audio previews at openpeon.com/packs.

How many sound packs are available?

165 packs across Warcraft, StarCraft, Red Alert, Portal, Zelda, Dota 2, Helldivers 2, Elder Scrolls, Duke Nukem, and more.The default install includes 5 curated packs:

peon (Warcraft III Orc Peon)
peasant (Warcraft III Human Peasant)
glados (Portal GLaDOS)
sc_kerrigan (StarCraft Sarah Kerrigan)
sc_battlecruiser (StarCraft Battlecruiser)

Install all packs:

peon packs install --all

Can I create my own sound pack?

Yes! Sound packs use the CESP (Coding Event Sound Pack Specification) with openpeon.json manifests.

Create a GitHub repo with openpeon.json + sound files
Tag a release (e.g., v1.0.0)
Submit to the OpenPeon registry

See the contributing guide and pack creation guide for step-by-step instructions.

Which IDEs are supported?

Claude Code — built-in hooks (primary)
Cursor — built-in adapter
OpenCode — native TypeScript plugin
GitHub Copilot — shell adapter
OpenAI Codex — shell adapter
Amp (Sourcegraph) — filesystem watcher
Gemini CLI — shell adapter
Kilo CLI — TypeScript plugin (OpenCode fork)
Kiro (Amazon) — shell adapter
Windsurf — shell adapter
Kimi Code (MoonshotAI) — filesystem watcher
Google Antigravity — filesystem watcher
OpenClaw — shell adapter
Any MCP client — Model Context Protocol server

See IDE adapters for setup instructions.

What events trigger sounds?

Event	CESP Category	Examples
Session starts	`session.start`	”Ready to work?”, “Yes?”, “What you want?”
Task finishes	`task.complete`	”Work, work.”, “Job’s done!”, “Okie dokie.”
Permission needed	`input.required`	”Something need doing?”, “Hmm?”
Tool/command error	`task.error`	”I can’t do that.”, “Son of a bitch!”
Task acknowledged	`task.acknowledge`	”I read you.”, “On it.” (disabled by default)
Rate/token limit	`resource.limit`	Pack-dependent
Rapid prompts (3+ in 10s)	`user.spam`	”Me busy, leave me alone!”

You can disable any category in your config:

peon
# Ask Claude: "Disable session.start sounds"

Can I adjust the volume?

Yes! Volume range is 0.0 (silent) to 1.0 (full).Set volume:

peon volume 0.7

Check current volume:

peon volume

Or ask Claude:

/peon-ping-config
# "Set volume to 0.5"

How do I get mobile push notifications?

PeonPing supports ntfy.sh (free, no account), Pushover, and Telegram.Quick start with ntfy.sh:

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

peon mobile ntfy my-peon-notifications

Pushover:

peon mobile pushover <user_key> <app_token>

Telegram:

peon mobile telegram <bot_token> <chat_id>

Test it:

peon mobile test

See mobile notifications for setup details.

What's the difference between overlay and standard notifications?

PeonPing supports two notification styles:Overlay (default):

Large, visible banners that appear on all screens
macOS: JXA Cocoa overlay
Windows/WSL/MSYS2: Windows Forms popup
Clicking focuses your terminal (supports Ghostty, Warp, iTerm2, Zed, Terminal.app)

Standard:

System notifications via terminal-notifier (macOS) or Windows toast (WSL/MSYS2)
Smaller, less intrusive
Clicking focuses your terminal if terminal-notifier is installed (brew install terminal-notifier)

Switch styles:

peon notifications overlay   # large banners (default)
peon notifications standard  # system notifications

Can I use different packs for different projects?

Yes! Use path_rules to assign packs based on working directory.Bind a pack to the current directory:

peon packs bind glados

Bind to a pattern:

peon packs bind --pattern "*/work/client-a/*" glados

List all bindings:

peon packs bindings

Remove current directory binding:

peon packs unbind

Or edit ~/.claude/hooks/peon-ping/config.json directly:

{
  "path_rules": [
    { "pattern": "*/work/client-a/*", "pack": "glados" },
    { "pattern": "*/personal/*", "pack": "peon" }
  ]
}

What's the CESP standard?

CESP (Coding Event Sound Pack Specification) is an open standard for mapping coding events to sounds that any agentic IDE can adopt.PeonPing implements CESP v1.0. Sound packs use openpeon.json manifests that map events to audio files.Read the full spec: openpeon.com/spec

Does PeonPing work with the MCP (Model Context Protocol)?

Yes! PeonPing includes an MCP server so any MCP client can play sounds directly via tool calls — no hooks required.The agent chooses the sound instead of automatically playing a fixed sound on every event.Setup:Add to your MCP client config (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "peon-ping": {
      "command": "node",
      "args": ["/path/to/peon-ping/mcp/peon-mcp.js"]
    }
  }
}

See MCP integration for details.

How do I uninstall PeonPing?

macOS/Linux:

bash ~/.claude/hooks/peon-ping/uninstall.sh

Windows (PowerShell):

powershell -File "$env:USERPROFILE\.claude\hooks\peon-ping\uninstall.ps1"

Keep sound packs (Windows):

powershell -File "$env:USERPROFILE\.claude\hooks\peon-ping\uninstall.ps1" -KeepSounds

The uninstaller removes hooks from settings.json, CLI shortcuts, and optionally sound packs.

Is PeonPing open source?

Yes! PeonPing is MIT licensed and open source.

Main repo: github.com/PeonPing/peon-ping
Registry: github.com/PeonPing/registry
Official packs: github.com/PeonPing/og-packs
CESP spec: github.com/PeonPing/openpeon

Contributions welcome!

Get Started

Core Features

Configuration

CLI Reference

Integrations

Advanced

Resources

Frequently Asked Questions

Build docs developers (and LLMs) love