---
type: reference
title: Pi Peon
description: CESP/OpenPeon sound-pack player for pi lifecycle events — peons, GLaDOS, battlecruisers, and 300+ community sound packs.
tags:
  - pi
  - package
  - sound
  - peon
  - cesp
  - openpeon
  - unverified
timestamp: 2026-08-28
---

# Pi Peon

**Package:** `@wierdbytes/pi-peon`
**Version:** 0.1.1
**Author:** wierdbytes

Plays CESP/OpenPeon sound packs on pi lifecycle events. Drop a sound pack into `~/.openpeon/packs/<name>/` or install from the community registry (300+ packs).

---

## Install

```bash
pi install @wierdbytes/pi-peon
```

## Sound Packs

Installed packs in `~/.openpeon/packs/`:

| Pack | Theme |
|------|-------|
| `peon` | Warcraft III Orc Peon (default) |
| `peasant` | Medieval peasant |
| `sc2_scv` | StarCraft II SCV |
| `ra2_soviet_engineer` | Red Alert 2 Soviet Engineer |
| `sc_battlecruiser` | StarCraft Battlecruiser |
| `zugzug` | Zugzug robot |

## Events

| pi Event | CESP Category |
|----------|---------------|
| `session_start` | `session.start` |
| `agent_start` | `task.acknowledge` |
| `agent_end` (used tools) | `task.complete` |
| `agent_end` (no tools) | `input.required` |
| `tool_result` (error) | `task.error` |
| Rate limit (429) | `resource.limit` |
| `task.progress` | `task.progress` |
| User spam (3 msgs/5s) | `user.spam` |

## Commands

| Command | Description |
|---------|-------------|
| `/peon` | Open settings modal |
| `/peon status` | Print active pack + config |
| `/peon mute` | Silence all categories |
| `/peon unmute` | Re-enable sounds |
| `/peon test [category]` | Play a random sound |
| `/peon reset` | Restore default config |

CLI flag `--no-peon` disables playback for one session.

## Settings

The `/peon` command opens an interactive settings modal with:

- **Packs** — Active, available, and registry packs
- **Volume** — Global volume control
- **Mute** — Per-event toggles
- **Registry browser** — Browse and install from community registry

---

## See Also

- [Pi Packages](index.md) — Package overview
- [pi](../index.md) — Pi configuration