沃克拉夫特III Peon语音通知

Install

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

Quickstart — `peon setup`

The fastest way to configure peon-ping is the interactive wizard:

peon setup

It walks you through every common setting in one go — press Enter at any prompt to keep the current value:

  ╔══════════════════════════════════════╗
  ║       peon-ping  setup wizard        ║
  ╚══════════════════════════════════════╝

  ── Volume ──
  > Volume (0.0 - 1.0) (0.5):

  ── Sound categories ──
  >   Session start [on/off] (on):
  >   Task acknowledge [on/off] (off):
  >   Task complete [on/off] (on):
  >   Task error [on/off] (on):
  >   Input required (permissions, questions) [on/off] (on):
  >   Resource limit (context compaction) [on/off] (on):
  >   User spam (rapid prompts) [on/off] (on):

  ── Notifications ──
  > Desktop notifications [on/off] (on):

  Overlay theme:
    1) Neon (cyberpunk)
    2) Glass (translucent)
    3) Sakura (cherry blossom)
    4) Jarvis (iron man)
  > Theme [neon]:

  Notification position:
    1) Top center
    2) Top right
    ...
  > Position [top-center]:

  Auto-dismiss:
    1) Persistent (click to dismiss)
    2) 3 seconds
    3) 4 seconds
    ...
  > Dismiss time [4]:

  ✓ Configuration saved!

What the wizard covers: - Volume — playback volume (0.0 – 1.0) - Sound categories — enable/disable each CESP category individually (session start, task complete, permission prompts, errors, etc.) - Desktop notifications — master switch for overlay banners - Overlay theme — choose the visual style (neon, glass, sakura, jarvis) - Position — where notifications appear (top-center, top-right, etc.) - Auto-dismiss — how long notifications stay visible (0 = persistent, click to dismiss)

When you're done, the wizard prints a summary and saves everything to ~/.claude/hooks/peon-ping/config.json. You can rerun peon setup anytime to tweak settings — it always shows your current values as defaults.

Tip: All individual peon subcommands (peon volume, peon notifications position top-right, etc.) still work if you prefer scripting or tweaking one setting at a time — see the Quick controls section.

Setup

Add to your MCP client config (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "peon-ping": {
      "command": "node",
      "args": ["/path/to/peon-ping/mcp/peon-mcp.js"]
    }
  }
}

If installed via Homebrew: $(brew --prefix peon-ping)/libexec/mcp/peon-mcp.js. See mcp/README.md for full setup instructions.

OpenAI Codex setup

Codex support uses an adapter and is not auto-registered by peon-ping-setup.

The Codex adapter expects the peon-ping runtime to exist at ~/.claude/hooks/peon-ping/, even if you only use Codex and do not use Claude Code.

Setup:

1. Install the peon-ping runtime first:

   bash "$(brew --prefix peon-ping)"/libexec/install.sh --no-rc
   

Or with the standard installer:

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

1. Add this to ~/.codex/config.toml:

   notify = ["bash", "~/.claude/hooks/peon-ping/adapters/codex.sh"]
   

1. Restart Codex.

If you installed with Homebrew, the runtime files are managed under ~/.claude/hooks/peon-ping/, and the Codex adapter forwards Codex notify events into that shared runtime.

Amp setup

A filesystem watcher adapter for Amp (by Sourcegraph). Amp doesn't expose event hooks like Claude Code, so this adapter watches Amp's thread files on disk and detects when the agent finishes a turn.

Setup:

1. Ensure peon-ping is installed (curl -fsSL https://peonping.com/install | bash)

1. Install fswatch (macOS) or inotify-tools (Linux):

   brew install fswatch        # macOS
   sudo apt install inotify-tools  # Linux
   

1. Start the watcher:

   bash ~/.claude/hooks/peon-ping/adapters/amp.sh        # foreground
   bash ~/.claude/hooks/peon-ping/adapters/amp.sh &       # background
   

Event mapping:

• New thread file created → Greeting sound ("Ready to work?", "Yes?")
• Thread file stops updating + agent finished turn → Completion sound ("Work, work.", "Job's done!")

How it works:

The adapter watches ~/.local/share/amp/threads/ for JSON file changes. When a thread file stops updating (1s idle timeout) and the last message is from the assistant with text content (not a pending tool call), it emits a Stop event — meaning the agent is done and waiting for your input.

Environment variables:

GitHub Copilot CLI setup

Native GitHub Copilot CLI integration with full CESP v1.0 conformance.

Recommended: user-level (global) wiring — no per-repo setup.

install.sh and install.ps1 automatically register Copilot CLI hooks at ~/.copilot/hooks/peon-ping.json whenever the ~/.copilot/ directory exists. Re-run the installer if you installed Copilot CLI after peon-ping. The wiring uses PascalCase event names, which tells Copilot CLI to deliver the VS Code-compatible (snake_case) payload that peon.sh / peon.ps1 reads natively — no per-repo adapter required.

Hooks registered globally:

postToolUse is intentionally not wired: peon has no PostToolUse handler and routing it through Stop floods the debounce window, swallowing real Stop events.

Prerequisite (Windows): Copilot CLI hooks require PowerShell 7+ (pwsh on PATH) and a permissive execution policy:

winget install Microsoft.PowerShell
powershell -NoProfile -Command "Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force"

Alternative: per-repository wiring with the adapter.

If you want Copilot CLI hooks committed to a specific repository (e.g. for a team workflow), use .github/hooks/hooks.json with the adapters/copilot.sh (or .ps1 on Windows) translator:

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh sessionStart",
        "powershell": "powershell -NoProfile -File %USERPROFILE%\\.claude\\hooks\\peon-ping\\adapters\\copilot.ps1 sessionStart"
      }
    ],
    "agentStop": [
      {
        "type": "command",
        "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh agentStop",
        "powershell": "powershell -NoProfile -File %USERPROFILE%\\.claude\\hooks\\peon-ping\\adapters\\copilot.ps1 agentStop"
      }
    ],
    "postToolUseFailure": [
      {
        "type": "command",
        "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh postToolUseFailure",
        "powershell": "powershell -NoProfile -File %USERPROFILE%\\.claude\\hooks\\peon-ping\\adapters\\copilot.ps1 postToolUseFailure"
      }
    ],
    "notification": [
      {
        "type": "command",
        "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh notification",
        "powershell": "powershell -NoProfile -File %USERPROFILE%\\.claude\\hooks\\peon-ping\\adapters\\copilot.ps1 notification"
      }
    ]
  }
}

Add additional events from the table above as desired. The adapter translates Copilot CLI's camelCase payload (sessionId, toolName, stopReason, etc.) to the snake_case shape (session_id, tool_name, stop_reason) that peon.sh / peon.ps1 reads.

Features:

• Sound playback via afplay (macOS), pw-play/paplay/ffplay (Linux), MediaPlayer/SoundPlayer (Windows) — same priority chain as the shell hook
• CESP event mapping — Copilot CLI hooks map to standard CESP categories (session.start, task.complete, task.error, input.required, user.spam, resource.limit)
• Desktop notifications — large overlay banners by default, or standard notifications
• Spam detection — detects 3+ rapid prompts within 10 seconds, triggers user.spam voice lines
• Debouncing — Stop events suppressed within a 5s window to prevent spam from chained tool calls

OpenCode setup

A native TypeScript plugin for OpenCode with full CESP v1.0 conformance.

Quick install:

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

The installer copies peon-ping.ts to ~/.config/opencode/plugins/ and creates a config at ~/.config/opencode/peon-ping/config.json. Packs are stored at the shared CESP path (~/.openpeon/packs/).

Features:

• Sound playback via afplay (macOS), pw-play/paplay/ffplay (Linux) — same priority chain as the shell hook
• CESP event mapping — session.created / session.idle / session.error / permission.asked / rapid prompt detection all map to standard CESP categories
• Desktop notifications — large overlay banners by default (JXA Cocoa, visible on all screens), or standard notifications via terminal-notifier / osascript. Fires only when the terminal is not focused.
• Terminal focus detection — checks if your terminal app (Terminal, iTerm2, Warp, Alacritty, kitty, WezTerm, ghostty, Hyper) is frontmost via AppleScript before sending notifications
• Tab titles — updates the terminal tab to show task status (● project: working... / ✓ project: done / ✗ project: error)
• Pack switching — reads default_pack from config (with active_pack fallback for legacy configs), loads the pack's openpeon.json manifest at runtime. path_rules can override the pack per working directory.
• No-repeat logic — avoids playing the same sound twice in a row per category
• Spam detection — detects 3+ rapid prompts within 10 seconds, triggers user.spam voice lines

<details> <summary>🖼️ Screenshot: desktop notifications with custom peon icon</summary>

</details>

Tip: Install terminal-notifier (brew install terminal-notifier) for richer notifications with subtitle and grouping support.

<details> <summary>🎨 Optional: custom peon icon for notifications</summary>

By default, terminal-notifier shows a generic Terminal icon. The included script replaces it with the peon icon using built-in macOS tools (sips + iconutil) — no extra dependencies.

bash <(curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/adapters/opencode/setup-icon.sh)

Or if installed locally (Homebrew / git clone):

bash ~/.claude/hooks/peon-ping/adapters/opencode/setup-icon.sh

The script auto-finds the peon icon (Homebrew libexec, OpenCode config, or Claude hooks dir), generates a proper .icns, backs up the original Terminal.icns, and replaces it. Re-run after brew upgrade terminal-notifier.

Future: When jamf/Notifier ships to Homebrew (#32), the plugin will migrate to it — Notifier has built-in --rebrand support, no icon hacks needed.

</details>

Kilo CLI setup

A native TypeScript plugin for Kilo CLI with full CESP v1.0 conformance. Kilo CLI is a fork of OpenCode and uses the same plugin system — this installer downloads the OpenCode plugin and patches it for Kilo.

Quick install:

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

The installer copies peon-ping.ts to ~/.config/kilo/plugins/ and creates a config at ~/.config/kilo/peon-ping/config.json. Packs are stored at the shared CESP path (~/.openpeon/packs/).

Features: Same as the OpenCode adapter — sound playback, CESP event mapping, desktop notifications, terminal focus detection, tab titles, pack switching, no-repeat logic, and spam detection.

Gemini CLI setup

A shell adapter for Gemini CLI with full CESP v1.0 conformance.

Setup:

1. Ensure peon-ping is installed (curl -fsSL https://peonping.com/install | bash)

1. Add the following hooks to your ~/.gemini/settings.json:

    {
      "hooks": {
        "SessionStart": [
          {
            "matcher": "startup",
            "hooks": [
              {
                "name": "peon-start",
                "type": "command",
                "command": "bash ~/.claude/hooks/peon-ping/adapters/gemini.sh SessionStart"
              }
            ]
          }
        ],
        "AfterAgent": [
          {
            "matcher": "*",
            "hooks": [
              {
                "name": "peon-after-agent",
                "type": "command",
                "command": "bash ~/.claude/hooks/peon-ping/adapters/gemini.sh AfterAgent"
              }
            ]
          }
        ],
        "AfterTool": [
          {
            "matcher": "*",
            "hooks": [
              {
                "name": "peon-after-tool",
                "type": "command",
                "command": "bash ~/.claude/hooks/peon-ping/adapters/gemini.sh AfterTool"
              }
            ]
          }
        ],
        "Notification": [
          {
            "matcher": "*",
            "hooks": [
              {
                "name": "peon-notification",
                "type": "command",
                "command": "bash ~/.claude/hooks/peon-ping/adapters/gemini.sh Notification"
              }
            ]
          }
        ]
      }
    }
   

Event mapping:

• SessionStart (startup) → Greeting sound ("Ready to work?", "Yes?")
• AfterAgent → Task completion sound ("Work, work.", "Job's done!")
• AfterTool → Success = Task completion sound, Failure = Error sound ("I can't do that.")
• Notification → System notification

Windsurf setup

Add to ~/.codeium/windsurf/hooks.json (user-level) or .windsurf/hooks.json (workspace-level):

{
  "hooks": {
    "post_cascade_response": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh post_cascade_response", "show_output": false }
    ],
    "pre_user_prompt": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh pre_user_prompt", "show_output": false }
    ],
    "post_write_code": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh post_write_code", "show_output": false }
    ],
    "post_run_command": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh post_run_command", "show_output": false }
    ]
  }
}

Kiro setup

Create ~/.kiro/agents/peon-ping.json:

{
  "name": "peon-ping",
  "hooks": {
    "agentSpawn": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/kiro.sh" }
    ],
    "userPromptSubmit": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/kiro.sh" }
    ],
    "stop": [
      { "command": "bash ~/.claude/hooks/peon-ping/adapters/kiro.sh" }
    ]
  }
}

preToolUse/postToolUse are intentionally excluded — they fire on every tool call and would be extremely noisy.

Rovo Dev CLI setup

A shell adapter for Rovo Dev CLI (Atlassian) with full CESP v1.0 conformance.

Auto-setup:

If ~/.rovodev/config.yml exists when you run install.sh or peon-ping-setup, event hooks are registered automatically.

Manual setup:

1. Ensure peon-ping is installed (curl -fsSL https://peonping.com/install | bash)

1. Add to ~/.rovodev/config.yml:

   eventHooks:
     events:
       - name: on_complete
         commands:
           - command: bash ~/.claude/hooks/peon-ping/adapters/rovodev.sh on_complete
       - name: on_error
         commands:
           - command: bash ~/.claude/hooks/peon-ping/adapters/rovodev.sh on_error
       - name: on_tool_permission
         commands:
           - command: bash ~/.claude/hooks/peon-ping/adapters/rovodev.sh on_tool_permission
   

1. Restart Rovo Dev CLI for the hooks to take effect.

Event mapping:

• on_complete → Completion sound ("Work, work.", "Job's done!")
• on_error → Error sound ("I can't do that.", "Son of a bitch!")
• on_tool_permission → Permission prompt sound ("Something need doing?", "Hmm?")

Features:

• Sound playback via afplay (macOS), pw-play/paplay/ffplay (Linux) — same priority chain as the shell hook
• CESP event mapping — Rovo Dev

Common Use Cases

Quick start

```bash peon trainer on # enable trainer peon trainer goal 200 # set daily goal (default: 300/300)

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 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:

```nix

Configuration

Slash commands and manual config

peon-ping also installs slash commands in Claude Code:

• /peon-ping-toggle — mute/unmute sounds
• /peon-ping-config — change any setting (volume, packs, categories, etc.)
• /peon-ping-rename <name> — give this session a custom name shown in notification titles and the terminal tab title (zero tokens, hook-intercepted); no argument resets to auto-detect

You can also just ask Claude to change settings for you — e.g. "enable round-robin pack rotation", "set volume to 0.3", or "add glados to my pack rotation". No need to edit config files manually.

Config location depends on install mode:

• Global install: $CLAUDE_CONFIG_DIR/hooks/peon-ping/config.json (default ~/.claude/hooks/peon-ping/config.json)
• Local install: ./.claude/hooks/peon-ping/config.json

{
  "volume": 0.5,
  "categories": {
    "session.start": true,
    "task.acknowledge": true,
    "task.complete": true,
    "task.error": true,
    "input.required": true,
    "resource.limit": true,
    "user.spam": true
  }
}

Schedule vs uniform goals

Exercises can have either a uniform daily goal (same every day) or a per-day schedule (different goals on different days). These are mutually exclusive:

• Setting a uniform goal removes any schedule for that exercise
• Setting a day-specific goal removes any uniform goal for that exercise

Days use short names: mon, tue, wed, thu, fri, sat, sun

peon trainer goal pushups 300         # 300 pushups every day (uniform)
peon trainer goal pushups mon 400     # Override: 400 on Monday (creates schedule)
peon trainer goal squats sun 0        # Rest day for squats on Sunday
peon trainer goal fri 150             # Light day for all exercises on Friday

On rest days (goal=0), reminders are skipped and status shows [REST DAY]. You can still log reps on rest days if you want.