PeonPing/peon-ping

peon‑ping – Audio & visual cues for AI‑coding assistants

What it is – peon‑ping is a lightweight helper that plugs into AI‑powered coding agents (Claude Code, GitHub Copilot, Cursor, etc.) and lets the agent speak to you. When the agent finishes a task, needs permission, hits an error, or any other notable event, peon‑ping plays a short voice line (often a meme‑style quote from games like Warcraft or Portal) and shows a bold on‑screen banner. The goal is to keep you in the flow without constantly watching the terminal or IDE.

How it works – The project ships a small CLI (peon) and a set of hooks that the supported agents call at key moments. Those hooks invoke the Coding Event Sound Pack Specification (CESP), which maps events such as task.complete or input.required to audio files stored in sound packs. The CLI also manages:

• Installing and switching sound packs (including community‑contributed ones).
• Controlling volume, which categories are audible, and whether desktop overlays are shown.
• Integration with remote development (WSL2, SSH, devcontainers) via an audio‑relay daemon.
• Optional mobile push notifications via the free ntfy service.

Key features

Feature	What you get
Broad agent support	Pre‑made adapters for Claude Code, Amp, GitHub Copilot, Codex, Cursor, Kiro, Qwen Code, and many others.
Cross‑platform	macOS, Linux, Windows, WSL2, MSYS2 – audio playback adapts automatically (WPF MediaPlayer, PlaySound, or ffmpeg‑transcoded WAV).
Sound packs	Ready‑made packs themed around game characters (e.g., GLaDOS, Kerrigan) and a registry for community packs. Packs can be installed, bound to a project, or rotated automatically.
Visual overlay	Large, configurable banners (neon, glass, sakura, Jarvis) appear on any screen, plus terminal tab title updates.
CLI control	peon toggle, peon volume 0.7, peon packs install …, peon preview, etc. All commands have tab‑completion.
Focus‑aware muting	Optionally silence sounds when macOS Do‑Not‑Disturb or a headset is detected.
Remote dev support	An audio‑relay daemon forwards sound from a container/SSH session to the host machine.
Mobile notifications	Free push via ntfy; set up with peon mobile ntfy <topic>.
Extensible config	JSON config stored under ~/.claude/hooks/peon-ping/ (or project‑local .claude/), plus an interactive peon setup wizard.

Typical workflow

1. Install via Homebrew, the provided script, or Nix.
2. Run peon setup – choose volume, which event categories you want sound for, overlay theme, etc.
3. The installer registers the appropriate hook scripts with your AI‑coding agent (e.g., adds entries to ~/.claude/settings.json).
4. As you code, the agent will automatically trigger sounds/overlays: “Work complete.” when a generation finishes, “Hmm?” when it needs your permission, etc.
5. Use peon toggle or the slash command /peon-ping-toggle in Claude Code to mute/unmute on the fly, or let the tool respect your macOS Focus mode.

Why you might want it – If you frequently let a coding assistant run in the background, you can lose track of when it finishes or hits a limit. peon‑ping gives you an audible and visual cue, letting you stay in the zone without constantly checking the IDE.

---

Installation shortcuts

• Homebrew (macOS/Linux): brew install PeonPing/tap/peon-ping && peon-ping-setup
• One‑liner script (macOS/Linux/WSL2): curl … | bash
• Windows PowerShell installer with -All, -Packs, -Local, etc.
• Nix: nix run github:PeonPing/peon-ping -- status

Further reading – See the live demo at https://peonping.com/, the CESP spec repo (github.com/PeonPing/openpeon), and the community pack registry (openpeon.com).