pi-peon-ping

A pi coding agent extension for peon-ping sound notifications. Plays themed audio clips on lifecycle events using OpenPeon sound packs (Warcraft III Peon, GLaDOS, Duke Nukem, StarCraft, and more).

Requirements

• pi >= 0.50.0
• An audio player on your system (see Platform support)

Features

| Event | Sound category | |-------|---------------| | Session start | session.start — "Ready to work?" | | Agent starts working | task.acknowledge — "Work, work." | | Tool error | task.error — error sound | | Rapid prompts (≥3 in 10s) | user.spam — annoyed voice line | | Agent finishes | task.complete — completion sound + desktop notification |

• /peon opens a settings panel to toggle sounds, switch packs, adjust volume, and enable/disable individual categories
• /peon install downloads the default 10 packs from the peon-ping registry
• Browsing packs previews each one as you scroll

Installation

Install as a pi package globally:

pi install npm:pi-peon-ping

For project-local installation:

pi install -l npm:pi-peon-ping

To try without installing:

pi -e npm:pi-peon-ping

You can also use the repository URL:

pi install git:github.com/joshuadavidthomas/pi-peon-ping
# or the full URL
pi install https://github.com/joshuadavidthomas/pi-peon-ping

For manual installation:

git clone https://github.com/joshuadavidthomas/pi-peon-ping ~/.pi/agent/extensions/pi-peon-ping

Usage

On first run, the extension will prompt you to install sound packs. You can also install them manually:

/peon install

Open the settings panel:

/peon

Platform support

| Platform | Player | |----------|--------| | macOS | afplay (built-in) | | Linux | pw-play, paplay, ffplay, mpv, play, or aplay (first found) | | WSL | PowerShell MediaPlayer |

Remote development

The extension auto-detects SSH sessions, devcontainers, and Codespaces, and routes audio through the peon-ping relay running on your local machine. See the peon-ping remote development docs for relay setup. The relay mode can be configured in /peon settings (auto / local / relay).

Config and data

The extension also picks up existing packs from ~/.claude/hooks/peon-ping/ if you have a Claude Code installation. Config and state are stored in ~/.config/peon-ping/.

Configuration options

Edit ~/.config/peon-ping/config.json or use the /peon settings panel:

| Option | Default | Description | |--------|---------|-------------| | default_pack | "peon" | Active sound pack | | volume | 0.5 | Sound volume (0.0–1.0) | | enabled | true | Master on/off switch | | desktop_notifications | true | Show system notifications on task complete | | silent_window_seconds | 0 | Suppress task.complete for tasks shorter than N seconds | | annoyed_threshold | 3 | Number of rapid prompts to trigger spam detection | | annoyed_window_seconds | 10 | Time window for spam detection | | relay_mode | "auto" | Relay mode: "auto", "local", or "relay" |

Note: If you have an existing config with active_pack, it will be automatically migrated to default_pack on next load.

Development

bun install            # Install dependencies
bun run test           # Run tests
bun run test:watch     # Run tests in watch mode
bun run typecheck      # Type check

To test the extension locally without conflicting with a globally installed copy:

pi -ne -e ./src/index.ts

-ne disables extension auto-discovery, -e loads only the local source.

License

pi-peon-ping is licensed under the MIT license. See the LICENSE file for more information.