See it in action → peonping.com

• 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

⚠️ In WSL2, ffmpeg must be installed to use sound packs that use formats other than WAV. In Debian distros, install with

sudo apt update; sudo apt install -y ffmpeg

Option 3: Installer for Windows

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.ps1" -UseBasicParsing | Invoke-Expression

Installs 5 curated packs by default (Warcraft, StarCraft, Portal). Re-run to update while preserving config/state. Or pick your packs interactively at peonping.com and get a custom install command.

Useful installer flags:

• --all — install all available packs
• --packs=peon,sc_kerrigan,... — install specific packs only
• --local — install packs, config, and hooks into ./.claude/ for the current project
• --global — explicit global install (same as default)
• --init-local-config — create ./.claude/hooks/peon-ping/config.json only

--local does not modify your shell rc files (no global peon alias/completion injection). Hooks are registered in the project-level ./.claude/settings.json with absolute paths so they work from any working directory within the project.

Examples:

curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash -s -- --all
curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash -s -- --packs=peon,sc_kerrigan
curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash -s -- --local

If a global install exists and you install local (or vice versa), the installer prompts you to remove the existing one to avoid conflicts.

Option 4: Clone and inspect first

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

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;

    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;
  };

  # Cursor hooks
  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
  };
}

IDE hooks: peon-ping Home Manager module will not setup your IDE hooks to avoid conflicting updates. You must define these hooks yourself (see example above) depending on how you usually manage your IDE configuration.

• peon-ping provide adapters scripts for various IDE such as cursor.sh - see adapters/
• You need to call them as your hook such command like

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

  See Cursor example above

What you'll hear

| Event | CESP Category | Examples | |---|---|---| | Session starts | session.start | "Ready to work?", "Yes?", "What you want?" | | Task finishes | task.complete | "Work, work.", "I can do that.", "Okie dokie." | | Permission needed | input.required | "Something need doing?", "Hmm?", "What you want?" | | Tool or command error | task.error | "I can't do that.", "Son of a bitch!" | | Agent acknowledged task | task.acknowledge | "I read you.", "On it." (disabled by default) | | Rate or token limit hit | resource.limit | "Zug zug." (pack dependent) | | Rapid prompts (3+ in 10s) | user.spam | "Me busy, leave me alone!" |

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 |

Other CLI commands:

peon pause                # Mute sounds
peon resume               # Unmute sounds
peon mute                 # Alias for 'pause'
peon unmute               # Alias for 'resume'
peon status               # Check if paused or active (concise)
peon status --ve