# peon-ping: Warcraft III voice notifications for Claude Code, Codex and other AI agents

> peon-ping hooks into AI coding agents and plays game character voice lines plus on-screen banners when the agent finishes or needs permission. It installs through Homebrew, an installer script or Nix, and it is MIT licensed.

**PeonPing/peon-ping** — Warcraft III Peon voice notifications (+ more!) for Claude Code, Codex, IDEs, and any AI agent. Stop babysitting your terminal. Employ a Peon today.

- Repository: https://github.com/PeonPing/peon-ping
- Website: https://www.peonping.com
- Stars: 5,055 · Forks: 391
- Language: Shell
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/peonping-peon-ping

## The gap peon-ping fills: agents that finish while you are looking elsewhere

An AI coding agent runs a long task, stops, and waits for a permission prompt. Nothing on screen changes in a way you notice from another window. The README states the problem plainly: agents do not notify you when they finish or need permission, you tab away, and you lose time getting back into flow. peon-ping is a notification layer for that moment.

The audience is narrow and specific. You need to be running one of the supported agents (Claude Code, Amp, GitHub Copilot, Codex, Grok Build, Cursor, OpenCode, Kilo CLI, Kiro, Kimi Code, Windsurf, Google Antigravity, Rovo Dev CLI, DeepAgents, Qwen Code, iFlow CLI, Trae, Kiro IDE, ECA, or any MCP client) and you need to care that a task ended. If your agent runs in a window you are already watching, or your tasks finish in seconds, the notification adds nothing.

The project is written in Shell, licensed MIT, and its last push was on 2026-08-30. It is not archived. The most recent release listed is v2.37.0 from 2026-08-26, with v2.36.0 and v2.35.1 before it, so releases arrive at a steady clip rather than once a year.

## How peon-ping intercepts agent events: hooks, adapters and an MCP server

The mechanism is event hooks, not polling. For Claude Code the README labels the integration a hook; for the rest of the list it uses the word adapter. The repository has an adapters/ directory and a skills/ directory at the top level, plus mcp/ for the MCP server. The install step registers those hooks into your agent's configuration and downloads sound packs.

When the agent fires the event, peon-ping plays a voice line and draws a banner. The README describes the output as game character voice lines plus visual overlay notifications, sourced from Warcraft, StarCraft, Portal, Zelda and others. Sound packs are the unit of content: you install a set of packs, and the notification draws from them.

There is a second path. The README says you can let the agent pick its own sound via MCP, which is why the project ships an MCP server and lists any MCP client as supported. That matters for agents that have no native hook system: instead of wiring an adapter, the agent calls the MCP server and requests a sound. The trade-off is that an MCP call is agent-initiated, so it only fires when the model decides to call it, whereas a hook fires on the agent's lifecycle event whether or not the model cooperates. For reliable "task finished" notifications, the hook path is the one that does not depend on model behaviour.

Windows and WSL2 get special handling. peon-ping plays audio on the Windows side of WSL2, and on first run it probes the Windows host once (cached per Windows build) to choose a playback path. On Windows 10 and Windows 11 before 24H2 it uses WPF MediaPlayer directly, with native MP3 and WAV and no extra dependencies. On Windows 11 24H2 and later (build 26100+), Microsoft removed legacy Windows Media Player, WPF MediaPlayer fails with MILAVERR_INVALIDWMPVERSION, and peon-ping falls back to System.Media.SoundPlayer, which is WAV-only. That fallback is the reason ffmpeg becomes a requirement for MP3 packs on recent Windows builds.

## Installing peon-ping and hearing the first voice line

Homebrew is the recommended path on macOS and Linux. The README gives this command:

```bash
brew install PeonPing/tap/peon-ping
```

After the formula installs, run peon-ping-setup to register hooks and download sound packs. Until that setup step runs, the binary exists but nothing is wired into your agent.

The script installer covers macOS, Linux and WSL2:

```bash
curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash
```

Piping a remote script into bash means you are trusting whatever main contains at that moment. If you want to read before you run, the README offers a clone-first option:

```bash
git clone https://github.com/PeonPing/peon-ping.git
cd peon-ping
./install.sh
```

On Windows the installer is PowerShell, and it installs a curated starter set of packs by default. Re-running it updates while preserving config and state, which is the upgrade path the README documents:

```powershell
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.ps1" -OutFile ".\install.ps1" -UseBasicParsing
powershell -ExecutionPolicy Bypass -File .\install.ps1
```

The Windows installer takes parameters: -All for every available pack, -Packs peon,sc_kerrigan to select specific ones, -Lang en,fr to filter by language, -Local to install packs, config, hooks and skills into ./.claude/ for the current project, and -InitLocalConfig to create ./.claude/hooks/peon-ping/config.json only. A project-local install does not install the global peon CLI shim or touch your PATH, and it registers hooks in the project-level ./.claude/settings.json with absolute paths so they work from any working directory inside the project.

Nix users can run it without installing, which is the cleanest way to check behaviour before committing:

```bash
nix run github:PeonPing/peon-ping -- status
nix run github:PeonPing/peon-ping -- packs install peon
```

The status subcommand is the first thing to run after any install. If it reports the hooks as registered, trigger your agent with a short task and a permission prompt, and you should hear a voice line and see a banner.

## Where peon-ping breaks: WSL2 audio, silent fallbacks and the ffmpeg dependency

The WSL2 audio path is the most concrete failure mode documented. On Windows 11 24H2 and later, the default automatic probe can land on System.Media.SoundPlayer, which only plays WAV. An MP3 pack then requires ffmpeg, installed on the WSL side:

```sh
sudo apt update; sudo apt install -y ffmpeg
```

The environment variable PEON_WSL_AUDIO_BACKEND controls the choice: auto probes and caches, mediaplayer forces WPF MediaPlayer over the WSL UNC path, and soundplayer forces a tmpfile copy with SoundPlayer. The README notes that forcing mediaplayer fails silently on 24H2 and later. Silent failure is the worst kind here, because a notification tool that stops notifying looks identical to an agent that has not finished. If you force that backend and hear nothing, the failure is in the audio path, not the agent.

The soundplayer path is described as universal but requiring ffmpeg for non-WAV files, so on a minimal WSL2 image you are adding a media transcoder to your development environment for notification sounds. That is a real cost on locked-down machines or CI-like containers.

A second boundary is scope. peon-ping is a notifier, not a supervisor. It does not queue tasks, retry failed agent runs, or report what the agent produced. If you need to know what the agent did, not just that it stopped, this is the wrong tool. And if you run agents in an environment where audio playback and a background MCP process are not acceptable, the whole premise does not apply.

## peon-ping against terminal bells and OS notification wrappers

The obvious alternative is what your terminal already does: a bell character or an OS notification from a shell wrapper. Those are strictly simpler. A wrapper around your agent command that calls notify-send or osascript on exit has no hooks, no adapters, no MCP server, and no sound packs to download. It also covers any command, not just the agents peon-ping has adapters for.

The difference in approach is where the event comes from. A shell wrapper only knows when the process exits. It cannot distinguish "agent finished the task" from "agent is waiting for permission" from "agent crashed", because all three look like the process ending. peon-ping hooks into the agent's own lifecycle events, so it can fire different sounds for different states, and it can fire while the agent is still running and blocked on a permission prompt. That is the specific capability a wrapper cannot replicate without parsing the agent's output.

The second alternative is the agent's own notification feature, where one exists. That keeps the dependency count at zero and stays inside the vendor's supported surface. What it does not give you is one configuration across Claude Code, Codex, Cursor and the rest of the list, or a shared pack library. If you run a single agent and it already notifies you, peon-ping is an extra layer with an extra installer. If you run three agents and want the same cue for all of them, the adapter approach is the reason to pick it.

## Maintenance, upgrades and what the MIT licence means for pack authors

Upgrades are cheap on the script path. The README states that re-running the Windows installer updates while preserving config and state, and the Homebrew path upgrades through the formula. The repository keeps a VERSION file and a CHANGELOG.md at the top level, and RELEASING.md documents the release process, so version-to-version changes are traceable without reading commit history.

The cost that is not zero is hook churn. Every install writes hook entries into your agent configuration, and a project-local install writes them into ./.claude/settings.json with absolute paths. Absolute paths mean the configuration is tied to where the project sits on disk. Move the directory and the hooks point at the old location. The README does not document a migration step for that case, so treat a directory move as a reinstall.

On licensing, the project is MIT. That is permissive for the code, but the sound packs are a separate question the README does not settle: the voice lines are described as coming from Warcraft, StarCraft, Portal and Zelda, which are commercial properties. The MIT licence on the repository does not by itself grant rights to redistribute audio ripped from those games. If you plan to publish a pack, or ship peon-ping inside a product, check the provenance of the audio you bundle rather than assuming the repository licence covers it. The .env.example file shows that pack creation can call the Deepgram API for auto-transcription and splitting, so pack tooling has an external service dependency of its own.

## Conclusion

Adopt peon-ping if you run Claude Code, Codex, Cursor or another supported agent in a terminal and keep losing focus while waiting for it to finish, and you are comfortable with a shell installer that registers hooks in your agent configuration. Skip it if you work in an environment where arbitrary audio playback or a background MCP server is not acceptable, or if you need per-notification policy control that the config does not expose. Before installing, read install.sh and the hooks it registers, check whether your agent appears in the adapter list, and confirm the WSL2 audio path on Windows 11 24H2 or later, where the README states MP3 packs need ffmpeg.

## FAQ

### What is peon-ping?

It is a notification tool that plays game character voice lines and shows on-screen banners when an AI coding agent finishes or needs attention. It supports Claude Code, Codex, Cursor, OpenCode and many other agents, plus any MCP client.

### Is peon-ping safe?

The repository is MIT licensed and written in Shell, and the primary install methods run install.sh or install.ps1, which register hooks in your agent configuration and download sound packs. The README offers a clone-and-inspect option for readers who want to read the script before running it.

### What is an alternative to peon-ping?

A shell wrapper that calls an OS notification command on process exit, or the notification feature built into your agent. The difference is that a wrapper only sees the process exit, while peon-ping hooks into the agent's own lifecycle events and can distinguish a finished task from a permission prompt.

## Sources

- [License: MIT](https://github.com/PeonPing/peon-ping/blob/main/LICENSE)
- [PeonPing/peon-ping on GitHub](https://github.com/PeonPing/peon-ping)
- [Project website](https://www.peonping.com)
- [README](https://github.com/PeonPing/peon-ping/blob/main/README.md)
- [Releases](https://github.com/PeonPing/peon-ping/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/peonping-peon-ping