peon-ping: Warcraft III voice notifications for AI coding agents
Warcraft III Peon voice notifications (+ more!) for Claude Code, Codex, IDEs, and any AI agent. Stop babysitting your terminal. Employ a Peon today.
At a glance
- What is it?
- peon-ping is an MIT-licensed shell-based notification layer that fires voice lines and on-screen banners when an AI coding agent finishes or needs permission. It solves a real focus problem, but it also installs hooks into your editor config and depends on host audio quirks, so the install path matters more than the pitch.
- Who is it for?
- peon-ping is for developers who run long agent sessions in a terminal or IDE and keep tabbing away, and who want audio plus visual notification without building their own hook scripts. It is not for teams that need a shared, auditable notification pipeline, since the tool registers hooks into per-user editor settings and plays audio through host-specific paths that vary by OS build.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 16 days ago.
- What is it written in?
- Mainly Shell, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What peon-ping actually notifies you about
The README states the problem directly: AI coding agents do not notify you when they finish or need permission. You tab away, lose focus, and lose time getting back into flow. peon-ping addresses that by playing game character voice lines and showing on-screen banners at those moments. The stated sources include Warcraft, StarCraft, Portal, and Zelda, and the project ships as a set of sound packs rather than a single fixed sound. The intended audience is anyone running an agent that can emit hook events: Claude Code, Amp, GitHub Copilot, Codex, Cursor, OpenCode, Windsurf, Google Antigravity, Qwen Code, and others listed as adapters. That is a wide surface, and it is the main reason to look at this project rather than writing a one-off notification script. The scope is deliberately narrow: it is a notification layer, not an agent orchestration tool, not a session manager, and not a replacement for the agent's own output. If your agent already surfaces a desktop notification natively and you find it sufficient, peon-ping adds little beyond novelty audio.
How the notification path works: hooks, adapters, and MCP
The mechanism visible in the material is hook-based. Installation registers hooks into editor or agent settings, and those hooks invoke peon-ping when the agent reaches a state that warrants attention. For Claude Code specifically, the README describes the integration as a hook. For the broader set of tools (Amp, Gemini CLI, GitHub Copilot, Codex, Grok Build, Cursor, OpenCode, Kilo CLI, Kiro, Kimi Code, Windsurf, Antigravity, OpenClaw, Rovo Dev CLI, DeepAgents, oh-my-pi, Qwen Code, iFlow CLI, Trae, Kiro IDE, ECA), the project uses what it calls adapters. That distinction matters: a hook is a native extension point in the agent, while an adapter is code peon-ping ships to translate that agent's event format into its own playback call. There is a second integration path, an MCP server, which the README describes as letting the agent pick its own sound. That inverts the flow: instead of the agent emitting an event that peon-ping interprets, the agent calls into peon-ping as a tool and selects a sound itself. The data flow is therefore one-directional in the hook case (agent event to hook to audio and banner) and request-driven in the MCP case (agent tool call to sound selection). Nothing in the material suggests peon-ping reads agent output, parses logs, or makes decisions about what the agent is doing. It reacts to state transitions the agent already exposes.
Installing it: Homebrew, installer scripts, and Windows parameters
There are several install paths, and they are not equivalent. The recommended one on macOS and Linux is Homebrew: brew install PeonPing/tap/peon-ping, followed by peon-ping-setup to register hooks and download sound packs. The second is a curl-piped installer: curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash, which the README lists for macOS, Linux, and WSL2. Windows has a PowerShell installer invoked with Invoke-WebRequest and then powershell -ExecutionPolicy Bypass -File .\install.ps1. That installer takes parameters worth knowing about: -All installs every available pack, -Packs peon,sc_kerrigan installs specific packs, -Lang en,fr filters by language, -Local installs packs, config, hooks, and skills into ./.claude/ for the current project only, -Global is the explicit form of the default, and -InitLocalConfig creates ./.claude/hooks/peon-ping/config.json only. The README notes that -Local does not install the global peon CLI shim or modify PATH, and that hooks are registered in the project-level ./.claude/settings.json with absolute paths so they work from any working directory inside the project. That last detail is the one to think about: absolute paths in a checked-in settings.json mean the hook will break for a teammate whose home directory differs. There is also a Nix path, with nix run github:PeonPing/peon-ping -- status and nix run github:PeonPing/peon-ping -- packs install peon shown as direct-from-source invocations. The README also offers a clone-and-inspect option for people who do not want to pipe a remote script into a shell, which is the reasonable default posture for a tool that writes into your editor configuration.
The WSL2 audio problem is the sharpest limitation
The most concrete constraint in the material is WSL2 audio. peon-ping plays audio on the Windows side, and on first run it probes the Windows host once, caching the result per Windows build, to choose a playback path. On Windows 10 and Windows 11 before 24H2, WPF MediaPlayer is used directly, which handles MP3 and WAV with no extra dependencies. On Windows 11 24H2 and later (build 26100 and up), Microsoft removed legacy Windows Media Player, and WPF MediaPlayer fails with MILAVERR_INVALIDWMPVERSION. The fallback is System.Media.SoundPlayer, which uses the Win32 PlaySound API. That works everywhere but is WAV-only, so MP3 packs require ffmpeg to transcode on the fly, installed with sudo apt update; sudo apt install -y ffmpeg. The backend can be forced with PEON_WSL_AUDIO_BACKEND set to auto, mediaplayer, or soundplayer. The README is explicit that forcing mediaplayer fails silently on 24H2 and later. Silent failure is the worst failure mode here, because a notification tool that does not notify is indistinguishable from an agent that has not finished. If you are on WSL2 with a recent Windows build and you skip the ffmpeg step, you may get no sound and no error. The documented workaround is to install ffmpeg or set the backend to soundplayer, but the underlying issue is that audio is delegated to a host that the project does not control.
Remote development and mobile notifications
The README lists remote development (SSH, devcontainers, Codespaces) and mobile notifications as supported scenarios, which is a meaningful expansion of scope. The install badges include SSH alongside macOS, WSL2, Linux, Windows, and MSYS2, so the project claims to handle environments where there is no local audio device. The material does not describe the mechanism for remote playback or for mobile delivery in the excerpt provided, so it is not possible to say from this material whether remote audio is forwarded, whether it plays on the client, or whether mobile notifications go through a push service. That is a gap worth checking in the repository before relying on it. The same applies to the MCP server: the README says the agent can pick its own sound via MCP, but the excerpt does not show the server configuration or the tool schema. If your interest in peon-ping is specifically the remote or mobile path, treat the feature list as a claim to verify rather than a documented workflow.
Sound packs, customization, and the maintenance question
peon-ping ships sound packs and documents creating your own, which is the part that determines whether the tool stays useful after the novelty wears off. The Windows installer's -Packs and -Lang parameters, and the Nix command packs install peon, both indicate that packs are installed as discrete units rather than bundled into the binary. The README also documents a Peon Trainer section and a debugging section, though the excerpt does not include their contents. On maintenance, the release cadence visible in the material is roughly monthly: v2.37.0 on 2026-08-26, v2.36.0 on 2026-08-10, v2.35.1 on 2026-07-24. That is frequent enough that pinning a version is worth considering if you install into a shared environment. The Windows installer explicitly supports re-running to update while preserving config and state, which is a deliberate design choice and a good sign for upgrade cost. The MIT license means you can fork, modify, and redistribute, including inside a commercial product, provided you keep the license text; this is a general statement about MIT and not legal advice. The practical license implication is that there is no copyleft obligation and no separate commercial tier described in the material, so the cost of adoption is your time, not a subscription.
What to compare it against, and what the comparison actually changes
The obvious alternative is the agent's own notification support. Claude Code, for example, has a hook system that can run arbitrary shell commands, and a few lines in a hook script can play a sound or send a desktop notification. That approach has no third-party dependency, no install script writing into your settings, and no adapter layer that can fall out of date when the agent changes its event format. The difference in approach is that peon-ping is a packaged, multi-agent abstraction with a curated set of sound packs and a setup command, while a hand-rolled hook is a few lines you fully control. The trade-off is real in both directions. peon-ping gives you consistent behavior across many agents and a selection of sounds without writing anything; a hand-rolled hook gives you no update surface and no dependency on whether an adapter has been updated for your agent's current version. If you use one agent and you are comfortable editing its settings file, the hand-rolled hook is likely the smaller commitment. If you switch between Claude Code, Codex, and Cursor in the same week, the adapter layer is the reason to use peon-ping. The material does not include a comparison with any other notification tool, so no other alternative can be assessed from what is available here.
Editorial conclusion
peon-ping is for developers who run long agent sessions in a terminal or IDE and keep tabbing away, and who want audio plus visual notification without building their own hook scripts. It is not for teams that need a shared, auditable notification pipeline, since the tool registers hooks into per-user editor settings and plays audio through host-specific paths that vary by OS build. Before adopting it, verify two things: whether your agent's hook format is actually supported by an existing adapter in the repository, and on WSL2, whether your Windows build is 24H2 or later, because that determines whether you need ffmpeg installed for MP3 packs. Run peon-ping status after install to confirm hooks registered and packs downloaded.
Community notes