peon-ping

<div align="center">

English | 한국어 | 中文 | 日本語

Game character voice lines + visual overlay notifications when your AI coding agent needs attention — or let the agent pick its own sound via MCP.

AI coding agents don't notify you when they finish or need permission. You tab away, lose focus, and waste 15 minutes getting back into flow. peon-ping fixes this with voice lines and bold on-screen banners from Warcraft, StarCraft, Portal, Zelda, and more — works with Claude Code, Amp, GitHub Copilot, Codex, Cursor, OpenCode, Kilo CLI, Kiro, Kimi Code, Windsurf, Google Antigravity, Rovo Dev CLI, DeepAgents, Qwen Code, iFlow CLI, Trae, Kiro IDE, ECA, and any MCP client.

See it in action → peonping.com

<video src="https://github.com/user-attachments/assets/149b6d15-65c2-41f2-9b56-13575ff8364b" autoplay loop muted playsinline width="400"></video>

</div>

---

• Install
• What you'll hear
• Quick controls
• Configuration
• Peon Trainer
• MCP server
• Multi-IDE support
• Remote development
• Mobile notifications
• Sound packs
• Debugging
• Uninstall
• Requirements
• How it works
• Links

---

Install

Option 1: Homebrew (recommended)

brew install PeonPing/tap/peon-ping

Then run peon-ping-setup to register hooks and download sound packs. macOS and Linux.

Option 2: Installer script (macOS, Linux, WSL2)

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

⚠️ WSL2 audio notes. peon-ping plays audio on the Windows side. On first run it probes your Windows host once (cached per Windows build) to pick the best playback path:

• On Windows 10 / Windows 11 pre-24H2, WPF MediaPlayer is used directly — native MP3 + WAV, no extra dependencies.

• On Windows 11 24H2+ (build 26100+), Microsoft removed legacy Windows Media Player from the OS and WPF MediaPlayer fails (MILAVERR_INVALIDWMPVERSION). peon-ping falls back to System.Media.SoundPlayer, which uses the Win32 PlaySound API and works everywhere — but it's WAV-only, so MP3 packs require ffmpeg to transcode on the fly:

  sudo apt update; sudo apt install -y ffmpeg
  

You can override the auto-detection with PEON_WSL_AUDIO_BACKEND=auto|mediaplayer|soundplayer:

• auto (default) — probe + cache as described above
• mediaplayer — force WPF MediaPlayer over the WSL UNC path (fails silently on 24H2+)
• soundplayer — force tmpfile copy + SoundPlayer (universal, requires ffmpeg for non-WAV files)

Option 3: Installer for Windows

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

Installs a curated starter set of packs by default. Re-run to update while preserving config/state. Or pick your packs interactively at peonping.com and get a custom install command.

Windows installer parameters:

• -All — install all available packs
• -Packs peon,sc_kerrigan,... — install specific packs only
• -Lang en,fr,... — install only packs matching language(s)
• -Local — install packs, config, hooks, and skills into ./.claude/ for the current project
• -Global — explicit global install (same as default)
• -InitLocalConfig — create ./.claude/hooks/peon-ping/config.json only

-Local does not install the global peon CLI shim or modify your user PATH. Hooks are registered in the project-level ./.claude/settings.json with absolute paths so they work from any working directory within the project.

Windows examples:

powershell -ExecutionPolicy Bypass -File .\install.ps1 -All
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Packs peon,sc_kerrigan
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Local
powershell -ExecutionPolicy Bypass -File .\install.ps1 -InitLocalConfig

If the initial download fails with a TLS error on older Windows PowerShell, run this once in the same session and retry:

[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12

Option 4: Clone and inspect first

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

On Windows PowerShell:

git clone https://github.com/PeonPing/peon-ping.git
Set-Location peon-ping
.\install.ps1

Option 5: Nix (macOS, Linux)

Run directly from source without installing:

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

Or install to your profile:

nix profile install github:PeonPing/peon-ping

Development shell (bats, shellcheck, nodejs):

nix develop  # or use direnv

Home Manager module (declarative configuration)

For reproducible setups, use the Home Manager module:

# In your home.nix or flake.nix
{ inputs, pkgs, ... }:

let
  peonCursorAdapterPath = "${inputs.peon-ping.packages.${pkgs.system}.default}/share/peon-ping/adapters/cursor.sh";
in {
  imports = [ inputs.peon-ping.homeManagerModules.default ];

  programs.peon-ping = {
    enable = true;
    package = inputs.peon-ping.packages.${pkgs.system}.default;
    claudeCodeIntegration = true;

    settings = {
      default_pack = "glados";
      volume = 0.7;
      enabled = true;
      desktop_notifications = true;
      categories = {
        "session.start" = true;
        "task.complete" = true;
        "task.error" = true;
        "input.required" = true;
        "resource.limit" = true;
        "user.spam" = true;
      };
    };

    # Install packs from og-packs (simple string notation)
    # and custom sources (attrset with name + src)
    installPacks = [
      "peon"
      "glados"
      "sc_kerrigan"
      # Custom pack from GitHub (openpeon.com registry)
      {
        name = "mr_meeseeks";
        src = pkgs.fetchFromGitHub {
          owner = "kasperhendriks";
          repo = "openpeon-mrmeeseeks";
          rev = "main";  # or use a commit hash for reproducibility
          sha256 = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
        };
      }
    ];
    enableZshIntegration = true;
  };

  # Optional extra IDE hooks, like Cursor
  home.file.".cursor/hooks.json".text = builtins.toJSON {
    version = 1;
    hooks = {
      afterAgentResponse = [{ command = "bash ${peonCursorAdapterPath} afterAgentResponse"; }];
      stop               = [{ command = "bash ${peonCursorAdapterPath} stop"; }];
    };
  };
}

Sound pack installation: The installPacks option supports two formats:

• Simple strings (e.g., "peon", "glados") — fetched from the og-packs repository
• Custom sources — attrset with name and src fields, where src can be any Nix fetcher result (e.g., pkgs.fetchFromGitHub)

For packs listed on openpeon.com, find the GitHub repository link and use pkgs.fetchFromGitHub:

{
  name = "pack_name";
  src = pkgs.fetchFromGitHub {
    owner = "github-owner";
    repo = "repo-name";
    rev = "main";  # or a commit hash/tag
    sha256 = "";   # Leave empty first, Nix will tell you the correct hash
  };
}

Claude Code hooks: set programs.peon-ping.claudeCodeIntegration = true; to install the Claude Code hook scripts under ~/.claude/hooks/peon-ping/ and merge the standard peon-ping hook entries into ~/.claude/settings.json.

Other IDE hooks: adapters for other IDEs are still opt-in so the module does not overwrite unrelated IDE settings. peon-ping provides adapter scripts such as cursor.sh in adapters/, and you can wire them like this:

${inputs.peon-ping.packages.${pkgs.system}.default}/share/peon-ping/adapters/$YOUR_IDE.sh EVENT_NAME

See the Cursor example above.

What you'll hear

| Event | CESP Category | Examples | |---|---|---| | Session starts | session.start | "Ready to work!", "Something need doing?" | | Task finishes | task.complete | "Work complete.", "Work, work." | | Agent acknowledged task | task.acknowledge | "I can do that.", "Be happy to.", "Okie dokie." (disabled by default) | | Permission needed | input.required | "Hmm?", "What you want?", "Yes?" | | Tool or command error | task.error | "Me not that kind of orc!", "Ugh." | | Rate or token limit hit | resource.limit | "Why not?" | | Rapid prompts (3+ in 10s) | user.spam | "Whaaat?", "Me busy, leave me alone!", "No time for play." |

Plus large overlay banners on every screen (macOS/WSL/MSYS2) and terminal tab titles (● project: done) — you'll know something happened even if you're in another app.

peon-ping implements the Coding Event Sound Pack Specification (CESP) — an open standard for coding event sounds that any agentic IDE can adopt.

Quick controls

Need to mute sounds and notifications during a meeting or pairing session? Two options:

| Method | Command | When | |---|---|---| | Slash command | /peon-ping-toggle | While working in Claude Code | | CLI | peon toggle | From any terminal tab |

Prefer it to happen automatically? Set focus_detect to have peon-ping honor macOS Focus / Do Not Disturb. Sounds and notifications go quiet whenever a Focus is on and resume when you turn it off. See also headphones_only and meeting_detect.

Other CLI commands:

Windows note: Windows currently supports the day-one controls (status, toggle, volume, core packs, notifications on/off, debug, logs, trainer). More advanced commands like setup, `rot