# peon-ping

Audio notifications for AI coding agents — when Claude Code finishes a task, asks for a permission, or hits an error, you hear a Warcraft III Peon voice line ("Work, work.", "Something need doing?", "Job's done."). Solves the "tab away from the terminal, miss the permission prompt for ten minutes" problem with the simplest possible mechanism: distinctive sound. The site claims peon-ping inspired VS Code to add native sound hooks for its 50M+ users (links Pierce Boggan's X post as the source).

Originally one bash script + a few `.wav` files. Has since grown into a small ecosystem: 160+ sound packs in 14 languages, an MCP server so the agent can pick its own sound, a workout-nag mode (Peon Trainer), and a separate Three.js desktop-pet repo (peon-pet) that animates an orc reacting to Claude Code events.

## Install

```
brew install PeonPing/tap/peon-ping
# or
curl -fsSL peonping.com/install | bash
```

Works on macOS, Linux, and WSL2. The site's homepage has a live install-command builder where you tick the sound packs you want and the curl command updates in place.

## How it integrates

Hooks rather than wrappers. The agent's existing hook system fires `peon-ping <category>` at the right moments — `greeting` on session start, `acknowledge` on a tool call, `complete` on stop, `error` on failure, `annoyed` on repeated permission prompts. The README lists adapters for Claude Code, Codex, Cursor, OpenCode, Kiro, Windsurf, Antigravity, Rovo Dev CLI, "and any IDE with hooks."

The MCP-server mode is the more interesting integration: instead of the harness firing the hook, the agent itself calls `play_sound` over MCP and picks the line based on what it just did. That makes the sound part of the agent's reasoning rather than a passive notification.

## Other features

- **Volume**: 0.0–1.0 in config (office-quiet)
- **No-repeat**: tracks the last clip per category so the same line never plays twice in a row
- **Category toggles**: enable/disable greeting / acknowledge / complete / error / annoyed independently
- **Tab titles**: terminal tab shows project name + status with a dot when done
- **Desktop notifications**: push alerts when the terminal isn't focused
- **Pack system**: 160+ packs across 14 languages; pack-author tooling at openpeon.com/create

## Peon Trainer

A 2.0 feature that turns the same hook surface into a workout coach: 300 pushups + 300 squats per day, nagged by a Peon. Session-start fires "Pushups first, code second!", a Claude Code slash skill (`/peon-ping-log 25 pushups`) logs reps without leaving the session, periodic ~20-minute reminders escalate if you slack. Hits the daily total and the Peon celebrates and stops nagging until tomorrow. Standalone-mode-able via `peon trainer on`.

## peon-pet

Separate repo: [github.com/PeonPing/peon-pet](https://github.com/PeonPing/peon-pet). macOS, Electron + Three.js. An animated orc sits in the corner of the screen and reacts to every Claude Code event — sleeping when idle, waking up on activity, typing alongside the agent, celebrating on done. Session dots show every active Claude Code window. Open source. Pure desktop-companion / vibe layer; doesn't add functionality beyond what peon-ping already does.

## Why it matters

Most "AI coding hook" tooling tries to make the agent more autonomous (charlie-daemons, botctl, etc — see [[charlie-daemons]] / [[botctl]]). peon-ping does the opposite: it leans into the human-attention model where the human supervises the agent and just wants better feedback signals when supervision is needed. Connects to the `[[agents-vs-daemons]]` distinction — peon-ping is squarely on the human-initiated-agent side and tries to make that pattern less exhausting rather than replacing it.

The character-voice framing also makes the sounds tolerable in a way that "ding" or "buzzer" notifications usually aren't. Distinctive enough to register; short enough to ignore once you're used to them; multiple voice lines per category so the brain doesn't tune them out.

## Repo

[github.com/PeonPing/peon-ping](https://github.com/PeonPing/peon-ping) — 4.6k stars, MIT, Shell primary, repo created 2026-02-09, last push 2026-05-01. Three months old, active.