@wierdbytes/pi-peon
Play CESP/OpenPeon sound packs on pi lifecycle events — peons, GLaDOS, battlecruisers and 300+ more community sound packs.
Package details
Install @wierdbytes/pi-peon from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@wierdbytes/pi-peon- Package
@wierdbytes/pi-peon- Version
0.2.0- Published
- Nov 20, 2026
- Downloads
- 288/mo · 24/wk
- Author
- wierdbytes
- License
- MIT
- Types
- extension
- Size
- 119 KB
- Dependencies
- 2 dependencies · 0 peers
Pi manifest JSON
{
"extensions": [
"./index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
@wierdbytes/pi-peon
CESP / OpenPeon sound-pack player for the pi coding agent.
"Work, work."
Drop a sound pack into ~/.openpeon/packs/<name>/ (or install one from
the community registry - 300+ packs:
peons, GLaDOS, Stronghold lords, StarCraft battlecruisers, ...) and pi
will play a clip on every notable lifecycle event.
Install
pi install npm:@wierdbytes/pi-peon
The default config points at the peon pack (Warcraft III Orc Peon).
If it isn't on disk yet, the extension auto-downloads it from the
community registry
on session_start. The pack ends up at ~/.openpeon/packs/peon/ and
the very first session.start clip plays as soon as the install
finishes — no restart needed.
What you hear
| pi event | CESP category |
|---|---|
session_start (startup / new) |
session.start |
agent_start |
task.acknowledge |
agent_end (turn used tools) |
task.complete |
agent_end (no tools, just chat) |
input.required |
tool_result with isError === true |
task.error |
after_provider_response with status === 429 |
resource.limit |
session_shutdown (reason "quit") |
session.end |
| user sending ≥ 3 messages in 5 s | user.spam |
session.end only plays with an external player (afplay, paplay, …):
the macOS in-process backend would be cut off as pi exits, so it skips it.
Every category can be toggled individually from the settings modal - the on-disk pack decides whether that category has actual sounds, and missing categories are silently skipped (per spec).
Commands
/peon open settings modal (active pack, volume, mute,
per-event toggles, registry browser, sound preview)
/peon status print active pack + player + config path
/peon mute silence every category until /peon unmute
/peon unmute
/peon test [category] play a random sound from the named category
(defaults to session.start). Bypasses debounce.
/peon reset restore default config
CLI flag --no-peon disables playback for one pi session without
touching the config.
Settings modal
Everything you can configure interactively lives behind /peon:
Packs… — one unified picker for everything pack-related. Opens a sectioned list with three groups:
- Active — the pack currently bound to events.
- Available — installed packs at
~/.openpeon/packs/. - Registry — everything else from
https://peonping.github.io/registry/index.json.
Keys inside the picker:
↑/↓— navigate (skips section headers).Enter— drill into the highlighted pack's sound files.Tab— set the highlighted pack as active. Downloads + installs automatically when the pack lives only in the registry.Esc— back to the main settings.- Type to substring-filter across pack id, display name, description, tags, language, and trust tier (case-insensitive).
Inside the files drill-in:
↑/↓— navigate the sound list (no filter row — a single pack rarely has more than ~30 clips).Enter— play the sound. Uses the local copy if the pack is installed; otherwise downloads just that one clip to$TMPDIR/peon-previews/and plays from there — no full-pack install needed for auditioning.Tab— set this sound's pack as the active pack (same install- if-needed logic).Esc— back to the packs picker.
Left/Right arrows are filter-cursor movement only — they don't drive navigation between submenus.
Master volume — 0–100. Scaled to each backend's native range (AVAudioPlayer's and afplay's
0.0–1.0, paplay's 0–65 536, ffplay's-volume 0–100).Muted — global kill switch.
Per-event toggles — one boolean per CESP category. The settings description tells you whether the active pack actually has sounds for that category.
Audio backends
Detected once per session; external players via which / where:
| Platform | Order tried |
|---|---|
| macOS | AVAudioPlayer in-process, then afplay |
| Linux | pw-play, paplay, ffplay, mpv, play, aplay |
| Windows | powershell.exe (System.Windows.Media.MediaPlayer) |
On macOS with Node ≥ 26.1, sounds play through AVAudioPlayer inside the
pi process (Node's experimental node:ffi, on a worker thread), so pi
stays one CoreAudio client however many sounds it plays. Spawning
afplay per sound makes each one a short-lived client; under bursts
(many sub-agents at once) coreaudiod can stop cleaning up after exited
clients, and all audio on the Mac crackles until it's restarted. Under
Bun or older Node, afplay is used as before.
aplay has no volume control; the master-volume setting is ignored
when it's the only backend.
Storage layout
~/.openpeon/packs/<pack>/
├── openpeon.json # CESP manifest
└── sounds/
├── *.wav | *.mp3 | *.ogg
~/.pi/agent/peon/
└── config.json # this extension's own config
Override the pack root with PEON_PACKS_DIR=/some/other/dir. Override
the state dir with the standard PI_AGENT_DIR.
Picker behaviour
- No-repeat - when a category has > 1 sound, the picker never picks the same one twice in a row.
- Debounce - events firing within 500 ms of the previous play of the same category are suppressed.
- User-spam cooldown -
user.spamre-fires at most once per 10 s.
Spec reference
Built against CESP 1.0. Manifest format, category-alias fallback, and tarball-from-GitHub install flow all follow the spec verbatim - packs that work in any other CESP-aware tool work here, and vice versa.
License
MIT — see LICENSE. Sound packs themselves ship under their
own licenses; see each pack's openpeon.json.