Skip to content
Back to search

peon-ping

SkillWorks with Claude CodeGitHub

Warcraft III Peon voice notifications (+ more!) for Claude Code, Codex, IDEs, and any AI agent. Stop babysitting your terminal. Employ a Peon today.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/peonping-peon-ping/badge.svg)](/listings/peonping-peon-ping)

HTML

<a href="/listings/peonping-peon-ping"><img src="/api/listings/peonping-peon-ping/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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](https://peonping.com/#picker)** 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,658 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # peon-ping
  2. <div align="center">
  3. **English** | [한국어](README_ko.md) | [中文](README_zh.md) | [日本語](README_ja.md)
  4. ![macOS](https://img.shields.io/badge/macOS-blue) ![WSL2](https://img.shields.io/badge/WSL2-blue) ![Linux](https://img.shields.io/badge/Linux-blue) ![Windows](https://img.shields.io/badge/Windows-blue) ![MSYS2](https://img.shields.io/badge/MSYS2-blue) ![SSH](https://img.shields.io/badge/SSH-blue)
  5. ![License](https://img.shields.io/badge/license-MIT-green)
  6. ![Claude Code](https://img.shields.io/badge/Claude_Code-hook-ffab01) ![Amp](https://img.shields.io/badge/Amp-adapter-ffab01) ![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-adapter-ffab01) ![GitHub Copilot](https://img.shields.io/badge/GitHub_Copilot-adapter-ffab01) ![Codex](https://img.shields.io/badge/Codex-adapter-ffab01) ![Grok Build](https://img.shields.io/badge/Grok_Build-adapter-ffab01) ![Cursor](https://img.shields.io/badge/Cursor-adapter-ffab01) ![OpenCode](https://img.shields.io/badge/OpenCode-adapter-ffab01) ![Kilo CLI](https://img.shields.io/badge/Kilo_CLI-adapter-ffab01) ![Kiro](https://img.shields.io/badge/Kiro-adapter-ffab01) ![Kimi Code](https://img.shields.io/badge/Kimi_Code-adapter-ffab01) ![Windsurf](https://img.shields.io/badge/Windsurf-adapter-ffab01) ![Antigravity](https://img.shields.io/badge/Antigravity-adapter-ffab01) ![OpenClaw](https://img.shields.io/badge/OpenClaw-adapter-ffab01) ![Rovo Dev CLI](https://img.shields.io/badge/Rovo_Dev_CLI-adapter-ffab01) ![DeepAgents](https://img.shields.io/badge/DeepAgents-adapter-ffab01) ![oh-my-pi](https://img.shields.io/badge/oh--my--pi-adapter-ffab01) ![Qwen Code](https://img.shields.io/badge/Qwen_Code-adapter-ffab01) ![iFlow CLI](https://img.shields.io/badge/iFlow_CLI-adapter-ffab01) ![Trae](https://img.shields.io/badge/Trae-adapter-ffab01) ![Kiro IDE](https://img.shields.io/badge/Kiro_IDE-adapter-ffab01) ![ECA](https://img.shields.io/badge/ECA-adapter-ffab01)
  7. **Game character voice lines + visual overlay notifications when your AI coding agent needs attention — or let the agent pick its own sound via MCP.**
  8. 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**, **Grok Build**, **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.
  9. **See it in action** &rarr; [peonping.com](https://peonping.com/)
  10. <video src="https://github.com/user-attachments/assets/149b6d15-65c2-41f2-9b56-13575ff8364b" autoplay loop muted playsinline width="400"></video>
  11. </div>
  12. ---
  13. - [Install](#install)
  14. - [What you'll hear](#what-youll-hear)
  15. - [Quick controls](#quick-controls)
  16. - [Configuration](#configuration)
  17. - [Peon Trainer](#peon-trainer)
  18. - [MCP server](#mcp-server)
  19. - [Multi-IDE support](#multi-ide-support)
  20. - [Remote development](#remote-development-ssh--devcontainers--codespaces)
  21. - [Mobile notifications](#mobile-notifications)
  22. - [Sound packs](#sound-packs)
  23. - [Creating packs](#creating-packs)
  24. - [Debugging](#debugging)
  25. - [Uninstall](#uninstall)
  26. - [Requirements](#requirements)
  27. - [How it works](#how-it-works)
  28. - [Links](#links)
  29. ---
  30. ## Install
  31. ### Option 1: Homebrew (recommended)
  32. ```bash
  33. brew install PeonPing/tap/peon-ping
  34. ```
  35. Then run `peon-ping-setup` to register hooks and download sound packs. macOS and Linux.
  36. ### Option 2: Installer script (macOS, Linux, WSL2)
  37. ```bash
  38. curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash
  39. ```
  40. ⚠️ **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:
  41. - On **Windows 10 / Windows 11 pre-24H2**, WPF MediaPlayer is used directly — native MP3 + WAV, no extra dependencies.
  42. - 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:
  43. ```sh
  44. sudo apt update; sudo apt install -y ffmpeg
  45. ```
  46. You can override the auto-detection with `PEON_WSL_AUDIO_BACKEND=auto|mediaplayer|soundplayer`:
  47. - `auto` (default) — probe + cache as described above
  48. - `mediaplayer` — force WPF MediaPlayer over the WSL UNC path (fails silently on 24H2+)
  49. - `soundplayer` — force tmpfile copy + `SoundPlayer` (universal, requires ffmpeg for non-WAV files)
  50. ### Option 3: Installer for Windows
  51. ```powershell
  52. Invoke-WebRequest -Uri "https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.ps1" -OutFile ".\install.ps1" -UseBasicParsing
  53. powershell -ExecutionPolicy Bypass -File .\install.ps1
  54. ```
  55. 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](https://peonping.com/#picker)** and get a custom install command.
  56. Windows installer parameters:
  57. - `-All` — install all available packs
  58. - `-Packs peon,sc_kerrigan,...` — install specific packs only
  59. - `-Lang en,fr,...` — install only packs matching language(s)
  60. - `-Local` — install packs, config, hooks, and skills into `./.claude/` for the current project
  61. - `-Global` — explicit global install (same as default)
  62. - `-InitLocalConfig` — create `./.claude/hooks/peon-ping/config.json` only
  63. `-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.
  64. Windows examples:
  65. ```powershell
  66. powershell -ExecutionPolicy Bypass -File .\install.ps1 -All
  67. powershell -ExecutionPolicy Bypass -File .\install.ps1 -Packs peon,sc_kerrigan
  68. powershell -ExecutionPolicy Bypass -File .\install.ps1 -Local
  69. powershell -ExecutionPolicy Bypass -File .\install.ps1 -InitLocalConfig
  70. ```
  71. If the initial download fails with a TLS error on older Windows PowerShell, run this once in the same session and retry:
  72. ```powershell
  73. [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
  74. ```
  75. ### Option 4: Clone and inspect first
  76. ```bash
  77. git clone https://github.com/PeonPing/peon-ping.git
  78. cd peon-ping
  79. ./install.sh
  80. ```
  81. On Windows PowerShell:
  82. ```powershell
  83. git clone https://github.com/PeonPing/peon-ping.git
  84. Set-Location peon-ping
  85. .\install.ps1
  86. ```
  87. ### Option 5: Nix (macOS, Linux)
  88. Run directly from source without installing:
  89. ```bash
  90. nix run github:PeonPing/peon-ping -- status
  91. nix run github:PeonPing/peon-ping -- packs install peon
  92. ```
  93. Or install to your profile:
  94. ```bash
  95. nix profile install github:PeonPing/peon-ping
  96. ```
  97. Development shell (bats, shellcheck, nodejs):
  98. ```bash
  99. nix develop # or use direnv
  100. ```
  101. #### Home Manager module (declarative configuration)
  102. For reproducible setups, use the Home Manager module:
  103. ```nix
  104. # In your home.nix or flake.nix
  105. { inputs, pkgs, ... }:
  106. let
  107. peonCursorAdapterPath = "${inputs.peon-ping.packages.${pkgs.stdenv.hostPlatform.system}.default}/share/peon-ping/adapters/cursor.sh";
  108. in {
  109. imports = [ inputs.peon-ping.homeManagerModules.default ];
  110. programs.peon-ping = {
  111. enable = true;
  112. package = inputs.peon-ping.packages.${pkgs.stdenv.hostPlatform.system}.default;
  113. claudeCodeIntegration = true;
  114. settings = {
  115. default_pack = "glados";
  116. volume = 0.7;
  117. enabled = true;
  118. desktop_notifications = true;
  119. categories = {
  120. "session.start" = true;
  121. "task.complete" = true;
  122. "task.error" = true;
  123. "input.required" = true;
  124. "resource.limit" = true;
  125. "user.spam" = true;
  126. };
  127. };
  128. # Install packs from og-packs (simple string notation)
  129. # and custom sources (attrset with name + src)
  130. installPacks = [
  131. "peon"
  132. "glados"
  133. "sc_kerrigan"
  134. # Custom pack from GitHub (openpeon.com registry)
  135. {
  136. name = "mr_meeseeks";
  137. src = pkgs.fetchFromGitHub {
  138. owner = "kasperhendriks";
  139. repo = "openpeon-mrmeeseeks";
  140. rev = "main"; # or use a commit hash for reproducibility
  141. sha256 = "sha256-AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
  142. };
  143. }
  144. ];
  145. enableZshIntegration = true;
  146. };
  147. # Optional extra IDE hooks, like Cursor
  148. home.file.".cursor/hooks.json".text = builtins.toJSON {
  149. version = 1;
  150. hooks = {
  151. afterAgentResponse = [{ command = "bash ${peonCursorAdapterPath} afterAgentResponse"; }];
  152. stop = [{ command = "bash ${peonCursorAdapterPath} stop"; }];
  153. };
  154. };
  155. }
  156. ```
  157. **Sound pack installation**: The `installPacks` option supports two formats:
  158. - **Simple strings** (e.g., `"peon"`, `"glados"`) — fetched from the [og-packs](https://github.com/PeonPing/og-packs) repository
  159. - **Custom sources** — attrset with `name` and `src` fields, where `src` can be any Nix fetcher result (e.g., `pkgs.fetchFromGitHub`)
  160. For packs listed on [openpeon.com](https://openpeon.com/), find the GitHub repository link and use `pkgs.fetchFromGitHub`:
  161. ```nix
  162. {
  163. name = "pack_name";
  164. src = pkgs.fetchFromGitHub {
  165. owner = "github-owner";
  166. repo = "repo-name";
  167. rev = "main"; # or a commit hash/tag
  168. sha256 = ""; # Leave empty first, Nix will tell you the correct hash
  169. };
  170. }
  171. ```
  172. **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`.
  173. **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/`](https://github.com/PeonPing/peon-ping/tree/main/adapters), and you can wire them like this:
  174. ```sh
  175. ${inputs.peon-ping.packages.${pkgs.stdenv.hostPlatform.system}.default}/share/peon-ping/adapters/$YOUR_IDE.sh EVENT_NAME
  176. ```
  177. See the Cursor example above.
  178. ## What you'll hear
  179. | Event | CESP Category | Examples |
  180. |---|---|---|
  181. | Session starts | `session.start` | *"Ready to work!"*, *"Something need doing?"* |
  182. | Task finishes | `task.complete` | *"Work complete."*, *"Work, work."* |
  183. | Agent acknowledged task | `task.acknowledge` | *"I can do that."*, *"Be happy to."*, *"Okie dokie."* *(disabled by default)* |
  184. | Permission needed | `input.required` | *"Hmm?"*, *"What you want?"*, *"Yes?"* |
  185. | Tool or command error | `task.error` | *"Me not that kind of orc!"*, *"Ugh."* |
  186. | Rate or token limit hit | `resource.limit` | *"Why not?"* |
  187. | Rapid prompts (3+ in 10s) | `user.spam` | *"Whaaat?"*, *"Me busy, leave me alone!"*, *"No time for play."* |
  188. 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.
  189. peon-ping implements the [Coding Event Sound Pack Specification (CESP)](https://github.com/PeonPing/openpeon) — an open standard for coding event sounds that any agentic IDE can adopt.
  190. ## Quick controls
  191. Need to mute sounds and notifications during a meeting or pairing session? Two options:
  192. | Method | Command | When |
  193. |---|---|---|
  194. | **Slash command** | `/peon-ping-toggle` | While working in Claude Code |
  195. | **CLI** | `peon toggle` | From any terminal tab |
  196. Prefer it to happen automatically? Set [`focus_detect`](#configuration) 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`.
  197. Other CLI commands:
  198. > 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`, `rotation`, `preview`, and `mobile` are tracked as follow-up Windows parity work.
  199. ```bash
  200. peon setup # Interactive setup wizard (volume, categories, notifications)
  201. peon pause # Mute sounds
  202. peon resume # Unmute sounds
  203. peon mute # Alias for 'pause'
  204. peon unmute # Alias for 'resume'
  205. peon status # Check if paused or active (concise)
  206. peon status --verbose # Show full details (notifications, headphones, IDEs, etc.)
  207. peon volume # Show current volume
  208. peon volume 0.7 # Set volume (0.0–1.0)
  209. peon rotation # Show current rotation mode
  210. peon rotation random # Set rotation mode (random|round-robin|session_override)
  211. peon packs list # List installed sound packs
  212. peon packs list --registry # Browse all available packs in the registry
  213. peon packs community # List all registry packs grouped by trust tier (Windows)
  214. peon packs search <query> # Search registry packs by name (Windows)
  215. peon packs install <p1,p2> # Install packs from the registry
  216. peon packs install --all # Install all packs from the registry
  217. peon packs install-local <path> # Install a pack from a local directory
  218. peon packs use <name> # Switch to a specific pack (auto-installs from registry on Windows)
  219. peon packs use --install <name> # Switch to pack, installing from registry if needed
  220. peon packs next # Cycle to the next pack
  221. peon packs remove <p1,p2> # Remove specific packs
  222. peon packs bind <name> # Bind a pack to the current directory
  223. peon packs bind --pattern <path> # Bind a pack to a directory pattern, e.g. "*/services"
  224. peon packs unbind # Remove the current directory
  225. peon packs bindings # List all assigned bindings
  226. peon packs ide-bind <ide> <name> # Bind a pack to an IDE id, e.g. codex
  227. peon packs ide-unbind <ide> # Remove an IDE binding
  228. peon packs ide-bindings # List all IDE-based bindings
  229. peon packs exclude add <path> # Silence sounds & notifications for a glob or directory
  230. peon packs exclude remove <path> # Stop silencing the given path
  231. peon packs exclude list # List silenced paths
  232. peon create # Draft a new sound pack via your own Claude Code (interactive, or --name/--flavor/--vibe)
  233. peon eval <name-or-path> # Open the eval gate to audition/reroll/approve a draft (or re-draft an installed pack)
  234. peon sounds list [pack] # List sounds in a pack, marking disabled ones
  235. peon sounds disable <category> <file> [--pack=<name>] # Mute a single sound within a pack
  236. peon sounds enable <category> <file> [--pack=<name>] # Re-enable a previously disabled sound
  237. peon notifications on # Enable desktop notifications
  238. peon notifications off # Disable desktop notifications
  239. peon notifications overlay # Use large overlay banners (default)
  240. peon notifications standard # Use standard system notifications
  241. peon notifications test # Send a test notification
  242. peon notifications position [pos] # Get/set notification position (top-left, top-center, top-right, bottom-left, bottom-center, bottom-right)
  243. peon notifications dismiss [N] # Get/set auto-dismiss time in seconds (0 = persistent)
  244. peon notifications label [text|reset] # Get/set project label override for notifications
  245. peon notifications template [key] [fmt] # Get/set/reset message templates (keys: stop, permission, error, idle, question)
  246. peon preview # Play all sounds from session.start
  247. peon preview <category> # Play all sounds from a specific category
  248. peon preview --list # List all categories in the active pack
  249. peon mobile ntfy <topic> # Set up phone notifications (free)
  250. peon mobile off # Disable phone notifications
  251. peon mobile test # Send a test notification
  252. peon debug on # Enable debug logging
  253. peon debug off # Disable debug logging
  254. peon debug status # Show debug state, log directory, file count, total size
  255. peon logs # Show last 50 lines of today's log
  256. peon logs --last N # Show last N lines across all log files
  257. peon logs --session ID # Filter today's log by session ID
  258. peon logs --session ID --all # Search all log files for session ID
  259. peon logs --clear # Delete all log files (with confirmation)
  260. peon relay --daemon # Start audio relay (for SSH/devcontainer)
  261. peon relay --stop # Stop background relay
  262. ```
  263. Available CESP categories for `peon preview`: `session.start`, `task.acknowledge`, `task.complete`, `task.error`, `input.required`, `resource.limit`, `user.spam`. (Extended categories `session.end` and `task.progress` are defined in the CESP spec and supported by pack manifests, but not currently triggered by built-in hook events.)
  264. Tab completion is supported — type `peon packs use <TAB>` to see available pack names.
  265. Pausing mutes sounds and desktop notifications instantly. Persists across sessions until you resume. Tab titles remain active when paused.
  266. ## Configuration
  267. ### Quickstart — `peon setup`
  268. The fastest way to configure peon-ping is the interactive wizard:
  269. ```bash
  270. peon setup
  271. ```
  272. It walks you through every common setting in one go — press **Enter** at any prompt to keep the current value:
  273. ```
  274. ╔══════════════════════════════════════╗
  275. ║ peon-ping setup wizard ║
  276. ╚══════════════════════════════════════╝
  277. ── Volume ──
  278. > Volume (0.0 - 1.0) (0.5):
  279. ── Sound categories ──
  280. > Session start [on/off] (on):
  281. > Task acknowledge [on/off] (off):
  282. > Task complete [on/off] (on):
  283. > Task error [on/off] (on):
  284. > Input required (permissions, questions) [on/off] (on):
  285. > Resource limit (context compaction) [on/off] (on):
  286. > User spam (rapid prompts) [on/off] (on):
  287. ── Notifications ──
  288. > Desktop notifications [on/off] (on):
  289. Overlay theme:
  290. 1) Neon (cyberpunk)
  291. 2) Glass (translucent)
  292. 3) Sakura (cherry blossom)
  293. 4) Jarvis (iron man)
  294. > Theme [neon]:
  295. Notification position:
  296. 1) Top center
  297. 2) Top right
  298. ...
  299. > Position [top-center]:
  300. Auto-dismiss:
  301. 1) Persistent (click to dismiss)
  302. 2) 3 seconds
  303. 3) 4 seconds
  304. ...
  305. > Dismiss time [4]:
  306. ✓ Configuration saved!
  307. ```
  308. **What the wizard covers:**
  309. - **Volume** — playback volume (0.0 – 1.0)
  310. - **Sound categories** — enable/disable each CESP category individually (session start, task complete, permission prompts, errors, etc.)
  311. - **Desktop notifications** — master switch for overlay banners
  312. - **Overlay theme** — choose the visual style (neon, glass, sakura, jarvis)
  313. - **Position** — where notifications appear (top-center, top-right, etc.)
  314. - **Auto-dismiss** — how long notifications stay visible (`0` = persistent, click to dismiss)
  315. 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.
  316. > **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](#quick-controls) section.
  317. ### Slash commands and manual config
  318. peon-ping also installs slash commands in Claude Code:
  319. - `/peon-ping-toggle` — mute/unmute sounds
  320. - `/peon-ping-config` — change any setting (volume, packs, categories, etc.)
  321. - `/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
  322. 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.
  323. Config location depends on install mode:
  324. - Global install: `$CLAUDE_CONFIG_DIR/hooks/peon-ping/config.json` (default `~/.claude/hooks/peon-ping/config.json`)
  325. - Local install: `./.claude/hooks/peon-ping/config.json`
  326. ```json
  327. {
  328. "volume": 0.5,
  329. "categories": {
  330. "session.start": true,
  331. "task.acknowledge": true,
  332. "task.complete": true,
  333. "task.error": true,
  334. "input.required": true,
  335. "resource.limit": true,
  336. "user.spam": true
  337. }
  338. }
  339. ```
  340. ### Independent Controls
  341. peon-ping has three independent controls that can be mixed and matched:
  342. | Config Key | Controls | Affects Sounds | Affects Desktop Popups | Affects Mobile Push |
  343. |------------|----------|----------------|------------------------|---------------------|
  344. | `enabled` | Master audio switch | ✅ Yes | ❌ No | ❌ No |
  345. | `desktop_notifications` | Desktop popup banners | ❌ No | ✅ Yes | ❌ No |
  346. | `mobile_notify.enabled` | Phone push notifications | ❌ No | ❌ No | ✅ Yes |
  347. This means you can:
  348. - Keep sounds but disable desktop popups: `peon notifications off`
  349. - Keep desktop popups but disable sounds: `peon pause`
  350. - Enable mobile push without desktop popups: set `desktop_notifications: false` and `mobile_notify.enabled: true`
  351. - **volume**: 0.0–1.0 (quiet enough for the office)
  352. - On macOS, `peon-play` routes audio to the Sound Effects output device when available. A 300 ms silent lead-in wakes idle devices, and a 500 ms silent tail lets buffered audio finish before the player exits. Concurrent local macOS events share one playback transaction, so each new sound interrupts the previous owned player instead of piling up. Direct helper calls can tune these with `-p <milliseconds>` and `-t <milliseconds>`; `-t 0` disables the tail.
  353. - **desktop_notifications**: `true`/`false` — toggle desktop notification popups independently from sounds (default: `true`). When disabled, sounds continue playing but visual popups are suppressed. Mobile notifications are unaffected.
  354. - **notification_style**: `"overlay"` or `"standard"` — controls how desktop notifications appear (default: `"overlay"`)
  355. - **overlay**: large, visible banners — JXA Cocoa overlay on macOS, Windows Forms popup on WSL/MSYS2. Clicking the overlay focuses your terminal (supports Ghostty, Warp, iTerm2, Zed, Terminal.app). On iTerm2, clicking focuses the correct tab/pane/window — not just the app.
  356. - **standard**: system notifications — [`terminal-notifier`](https://github.com/julienXX/terminal-notifier) / `osascript` on macOS, Windows toast on WSL/MSYS2. When `terminal-notifier` is installed (`brew install terminal-notifier`), clicking a standard notification focuses your terminal automatically (supports Ghostty, Warp, iTerm2, Zed, Terminal.app). On native Windows, clicking a toast notification focuses the IDE or terminal window (supports VS Code, Cursor, Windsurf, Windows Terminal, PowerShell). With multiple windows open, the notification targets the exact window that originated the event via PID-based process tree matching.
  357. - Direct Ghostty sessions use native OSC 777 notifications in `standard` style, so a click targets the emitting tab/split. herdr, tmux, cmux, custom click commands, or an unavailable session TTY retain their existing system-notification route.
  358. - **overlay_theme**: `"jarvis"`, `"glass"`, `"sakura"`, or omit for the default overlay — macOS only (default: none)
  359. - **jarvis**: circular HUD with rotating arcs, graduation ticks, and progress ring
  360. - **glass**: glassmorphism panel with accent color bar, progress line, and timestamp
  361. - **sakura**: zen garden with bonsai tree and animated cherry blossom petals
  362. - **categories**: Toggle individual CESP sound categories on/off (e.g. `"session.start": false` to disable greeting sounds)
  363. - **annoyed_threshold / annoyed_window_seconds**: How many prompts in N seconds triggers the `user.spam` easter egg
  364. - **silent_window_seconds**: Suppress `task.complete` sounds and notifications for tasks shorter than N seconds. (e.g. `10` to only hear sounds for tasks that take longer than 10 seconds)
  365. - **session_start_cooldown_seconds** (number, default: `30`): Deduplicates greeting sounds when multiple workspaces start at the same time (e.g. opening OpenCode or Cursor with many folders). Only the first session start plays the greeting; subsequent ones within this window stay silent. Set to `0` to disable deduplication and always play a greeting.
  366. - **suppress_idle_prompt_repeats** (boolean, default: `true`): Claude Code re-fires its `idle_prompt` notification every ~60s while the terminal is unfocused. peon-ping routes `idle_prompt` to `task.complete` so you still get a sound when input is needed — but without dedupe the same sound replays on every poke. When `true`, an `idle_prompt` is suppressed if a `task.complete` for the same session already fired inside `idle_prompt_suppress_window_seconds`. Set to `false` to restore the periodic nudge.
  367. - **idle_prompt_suppress_window_seconds** (number, default: `3600`): Window used by `suppress_idle_prompt_repeats`. After a `task.complete` fires for a session, subsequent `idle_prompt` notifications for that session stay silent for this many seconds. Set to `0` to disable the window (effectively the same as `suppress_idle_prompt_repeats: false`).
  368. - **suppress_subagent_complete** (boolean, default: `false`): Suppress sounds and notifications from sub-agent activity. When Claude Code's Task tool dispatches parallel sub-agents, each one fires its own events: a completion sound on finish, `task.error` on failed Bash commands, `input.required` on permission requests. Set this to `true` to hear only the parent session's sounds. Events fired from inside a sub-agent are detected via the `agent_id` field Claude Code adds to their hook payloads; separate-session sub-agents (older clients, other IDEs) are still detected by the SubagentStart timing heuristic.
  369. - **subagent_input_required** (boolean, default: `false`): Only meaningful with `suppress_subagent_complete: true`. Claude Code passes a sub-agent's permission prompts (and MCP elicitation dialogs) through to you in the parent session, and the sub-agent blocks until you answer. Set this to `true` to keep `input.required` sounds and notifications for those prompts while every other sub-agent event stays silent.
  370. - **default_pack**: The fallback pack used when no more specific rule applies (default: `"peon"`). Replaces the old `active_pack` key — existing configs are migrated automatically on `peon update`.
  371. - **path_rules**: Array of `{ "pattern": "...", "pack": "..." }` objects. Assigns a pack to sessions based on the working directory using glob matching (`*`, `?`). First matching rule wins. Beats `pack_rotation` and `default_pack`; overridden by `session_override` assignments.
  372. ```json
  373. "path_rules": [
  374. { "pattern": "*/work/client-a/*", "pack": "glados" },
  375. { "pattern": "*/personal/*", "pack": "peon" }
  376. ]
  377. ```
  378. - **exclude_dirs**: Array of glob or directory patterns. If the current working directory matches one of these entries, **all sounds and notifications are silenced** for that invocation (the hook logs `suppressed=True reason=excluded_dir pattern=<match>`). Bare directory paths also match descendants, so `"~/conductor/workspaces"` silences everything under that tree. Use this for noisy background agents (e.g. `CodexBar/ClaudeProbe`), throwaway scratch dirs, or sensitive workspaces where audio alerts are unwanted.
  379. ```json
  380. "exclude_dirs": [
  381. "~/conductor/workspaces",
  382. "~/Library/Application Support/CodexBar*"
  383. ]
  384. ```
  385. - **ide_rules**: Array of `{ "ide": "...", "pack": "..." }` objects. Assigns a pack by IDE/source after `path_rules` and before rotation/default fallback. First matching rule wins. Common ids: `claude`, `codex`, `cursor`, `opencode`, `kilo`, `kiro`, `gemini`, `copilot`, `windsurf`, `kimi`, `antigravity`, `amp`, `deepagents`, `openclaw`, `rovodev`.
  386. ```json
  387. "ide_rules": [
  388. { "ide": "codex", "pack": "glados" },
  389. { "ide": "claude", "pack": "peon" }
  390. ]
  391. ```
  392. - **pack_rotation**: Array of pack names (e.g. `["peon", "sc_kerrigan", "peasant"]`). Used when `pack_rotation_mode` is `random` or `round-robin`. Leave empty `[]` to use `default_pack` (or `path_rules` / `ide_rules`) only.
  393. - **pack_rotation_mode**: `"random"` (default), `"round-robin"`, or `"session_override"`. With `random`/`round-robin`, each independent session picks one pack from `pack_rotation`, even when other sessions are active in the same directory. Resuming or compacting a known session keeps its pack. A compact event with a new session ID inherits only when recent activity matches both its terminal and directory; a separate subagent session inherits only when its `agent_id` matches the parent's recent `SubagentStart`. With `session_override`, the `/peon-ping-use <pack>` command assigns a pack per session. Invalid or missing packs fall back through the hierarchy. (`"agentskill"` is accepted as a legacy alias for `"session_override"`.)
  394. - **session_ttl_days** (number, default: 7): Expire stale per-session pack assignments older than N days. Keeps `.state.json` from growing unbounded when using `session_override` mode.
  395. - **headphones_only** (boolean, default: `false`): Only play sounds when headphones or external audio devices are detected. When enabled, sounds are suppressed if built-in speakers are the active output — useful for open offices. Check status with `peon status`. Supported on macOS (via `system_profiler`) and Linux (via PipeWire `wpctl` or PulseAudio `pactl`).
  396. - **terminal_tab_title** (boolean, default: `true`): Update the terminal tab title with the current session status (for example `● project: done`). Set to `false` if you already manage tab titles with your own shell prompt or terminal automation and only want peon-ping's sounds/notifications.
  397. - **tmux_passthrough** (boolean, default: `false`): Pass the tab title and iTerm2 tab-color escapes through tmux's DCS passthrough to the host terminal (requires tmux 3.3a+ with `set -g allow-passthrough on`). Off by default because a tmux client multiplexes many panes/windows onto a single host terminal tab with no per-pane addressing: when several agent sessions run at once, every hook (including from background panes) repaints that one shared tab on a last-writer-wins basis, so it no longer reflects any single session. Leave it off and let tmux's own window/status line carry per-session state; enable it only if you run one tmux window per terminal tab (so 1 tab = 1 session). Has no effect outside tmux, where the escapes are always emitted.
  398. - **suppress_sound_when_tab_focused** (boolean, default: `false`): Skip sound playback when the terminal tab that generated the hook event is the currently active/focused tab. Sounds still play for background tabs as an alert that something happened elsewhere. Desktop and mobile notifications are unaffected. Useful when you only want audio cues from tabs you're not watching. macOS only (uses `osascript` to check frontmost app and iTerm2 tab focus). Ghostty suppression requires an exact terminal TTY from its scripting API; versions without that property keep notifications enabled rather than guessing from a shared title or directory.
  399. - **meeting_detect** Detects if the microphone is currently being used and temporarily suppresses the audio only until the microphone is no longer in use. Notification still appears.
  400. - **focus_detect** (boolean, default: `false`): Honor macOS **Focus / Do Not Disturb**. peon-ping plays sounds via `afplay` and draws overlays in a custom window, and both bypass Notification Center, so the system Focus toggle has no effect on them by default. When enabled, peon-ping reads the Focus state directly and suppresses output whenever **any** Focus (Do Not Disturb, Work, Sleep, etc.) is active, then resumes automatically when you turn Focus off. Mobile push (if configured) is unaffected, since your phone honors its own Focus. macOS only, and it fails open (if the Focus state can't be read, sounds play as normal).
  401. - **focus_detect_mode** (string, default: `"all"`): What `focus_detect` suppresses while a Focus is active. `"all"` mutes both the sound and the overlay/desktop notification. `"sound"` mutes only the sound (notifications still appear). `"notifications"` mutes only the notification (sound still plays). Ignored when `focus_detect` is `false`.
  402. - **notification_position** (string, default: `"top-center"`): Where overlay notifications appear on screen. Options: `"top-left"`, `"top-center"`, `"top-right"`, `"bottom-left"`, `"bottom-center"`, `"bottom-right"`.
  403. - **notification_dismiss_seconds** (number, default: `4`): Auto-dismiss overlay notifications after N seconds. Set to `0` for persistent notifications that require a click to dismiss.
  404. - **notification_all_screens** (boolean, default: `true`): Show overlay notifications on all screens (`true`) or only the main screen (`false`). Themed overlays (`glass`, `jarvis`, `sakura`) previously only showed on one screen — existing configs with those themes are migrated to `false` automatically. macOS only.
  405. - **`CLAUDE_SESSION_NAME` env var**: Set before launching `claude` to give a session a custom name. Shows in both desktop notification titles and terminal tab titles. Priority over all config-based naming. Example: `CLAUDE_SESSION_NAME="Auth Refactor" claude` or `export CLAUDE_SESSION_NAME="Feature: Auth"` then `claude`. Each terminal gets its own title automatically since peon-ping runs as a child of that Claude instance.
  406. - **notification_title_override** (string, default: `""`): Override the project name shown in notification titles. When empty, the project name is auto-detected from `/peon-ping-rename` > `CLAUDE_SESSION_NAME` > `.peon-label` > `notification_title_script` > `project_name_map` > git repo name > folder name.
  407. - **notification_title_marker** (string, default: `"●"`): Character(s) shown before the project name in notification titles and terminal tab titles. Desktop notification titles use `Project` by default; terminal tab titles keep `Project: status`. Set to `""` to disable. Example: `"🔔"`.
  408. - **notification_title_ide** (boolean, default: `false`): Include the normalized IDE label in desktop notification titles as `Project - IDE`. When disabled, the title stays `Project` and the message/body carries the status/details.
  409. - **notification_title_script** (string, default: `""`): Shell command run at event time to compute the project name dynamically. Receives env vars: `PEON_SESSION_ID`, `PEON_CWD`, `PEON_HOOK_EVENT`, `PEON_IDE`, `PEON_SESSION_NAME`. Use stdout (trimmed, max 50 chars); non-zero exit falls through to the next tier. `PEON_IDE` is the normalized IDE/source id such as `codex` or `claude`. Example: `"basename $PEON_CWD"`.
  410. - **project_name_map** (object, default: `{}`): Map directory paths to custom project labels for notifications. Keys are path patterns, values are display names. Example: `{ "/home/user/work/client-a": "Client A" }`.
  411. - **notification_templates** (object, default: `{}`): Custom message/body format strings for notification events. Keys are event types (`stop`, `permission`, `error`, `idle`, `question`), values are template strings with variable substitution. Available variables: `{project}`, `{ide}`, `{ide_id}`, `{summary}`, `{tool_name}`, `{status}`, `{event}`. Example: `{ "stop": "{status}: {summary}", "permission": "{status}: {tool_name}" }`.
  412. ### Pack Selection Hierarchy
  413. peon-ping resolves which sound pack to use through a 6-layer hierarchy. The first layer that produces a valid, installed pack wins:
  414. | Priority | Layer | Source | How to set |
  415. |----------|-------|--------|------------|
  416. | 1 (highest) | **session_override** | Per-session assignment | `/peon-ping-use <pack>` skill or MCP |
  417. | 2 | **path_rules** | Glob match on working directory | `peon packs bind` or `path_rules` in config |
  418. | 3 | **ide_rules** | IDE/source match | `peon packs ide-bind` or `ide_rules` in config |
  419. | 4 | **pack_rotation** | Random or round-robin from a list | `pack_rotation` array + `pack_rotation_mode` in config |
  420. | 5 | **default_pack** | Static fallback | `peon packs use <name>` or `default_pack` in config |
  421. | 6 (lowest) | **hardcoded** | Built-in default | `"peon"` |
  422. If a layer references a pack that is not installed, it falls through to the next layer.
  423. If `exclude_dirs` matches the current working directory, the entire invocation is silenced — no sound, no notification.
  424. ### Per-Project Pack Assignment (path_rules)
  425. Assign different sound packs to different projects based on directory path. Use the CLI or edit `config.json` directly.
  426. **CLI (recommended):**
  427. ```bash
  428. peon packs bind glados # Bind glados to the current directory
  429. peon packs bind sc_kerrigan --pattern "*/services/*" # Bind to a glob pattern
  430. peon packs bind duke_nukem --install # Bind and install from registry if needed
  431. peon packs unbind # Remove binding for the current directory
  432. peon packs unbind --pattern "*/services/*" # Remove a specific pattern binding
  433. peon packs bindings # List all bindings
  434. ```
  435. **Manual config:**
  436. ```json
  437. "path_rules": [
  438. { "pattern": "*/work/client-a/*", "pack": "glados" },
  439. { "pattern": "*/personal/*", "pack": "peon" },
  440. { "pattern": "*/services/*", "pack": "sc_kerrigan" }
  441. ]
  442. ```
  443. Rules use glob matching (`*`, `?`). First matching rule wins. Path rules override `pack_rotation` and `default_pack` but are overridden by `session_override` assignments.
  444. ### Per-IDE Pack Assignment (ide_rules)
  445. Use this layer when a path is noisy or shared across tools and you want a pack to follow the IDE instead.
  446. **CLI (recommended):**
  447. ```bash
  448. peon packs ide-bind codex glados # Use glados for Codex sessions
  449. peon packs ide-bind claude peon # Use peon for Claude Code
  450. peon packs ide-unbind codex # Remove one IDE rule
  451. peon packs ide-bindings # List IDE rules and recent detections
  452. ```
  453. **Manual config:**
  454. ```json
  455. "ide_rules": [
  456. { "ide": "codex", "pack": "glados" },
  457. { "ide": "claude", "pack": "peon" }
  458. ]
  459. ```
  460. `ide_rules` run after `path_rules`.
  461. ## Common Use Cases
  462. ### Sounds without popups
  463. Want voice feedback but no visual distractions?
  464. ```bash
  465. peon notifications off
  466. ```
  467. This keeps all sound categories playing while suppressing desktop notification banners. Mobile notifications (if configured) continue working.
  468. You can also use the alias:
  469. ```bash
  470. peon popups off
  471. ```
  472. ### Silent mode with notifications only
  473. Want visual alerts but no audio?
  474. ```bash
  475. peon pause # or set "enabled": false in config
  476. ```
  477. With `desktop_notifications: true`, you'll get popups but no sounds.
  478. ### Complete silence
  479. Disable everything:
  480. ```bash
  481. peon pause
  482. peon notifications off
  483. peon mobile off
  484. ```
  485. ## Peon Trainer
  486. Your peon is also your personal trainer. Built-in Pavel-style daily exercise mode — the same orc who tells you "work work" now tells you to drop and give him twenty.
  487. ### Quick start
  488. ```bash
  489. peon trainer on # enable trainer
  490. peon trainer goal 200 # set daily goal (default: 300/300)
  491. # ... code for a while, peon nags you every ~20 min ...
  492. peon trainer log 25 pushups # log what you did
  493. peon trainer log 30 squats
  494. peon trainer status # check progress
  495. ```
  496. ### How it works
  497. Trainer reminders piggyback on your coding session. When you start a new session, the peon immediately encourages you to start strong with pushups before you write any code. Then every ~20 minutes of active coding, you'll hear the peon yelling at you to do more reps. No background daemon needed. Log your reps with `peon trainer log`, and progress resets automatically at midnight.
  498. ### Commands
  499. | Command | Description |
  500. |---------|-------------|
  501. | `peon trainer on` | Enable trainer mode |
  502. | `peon trainer off` | Disable trainer mode |
  503. | `peon trainer status` | Show today's progress |
  504. | `peon trainer log <n> <exercise>` | Log reps (e.g. `log 25 pushups`) |
  505. | `peon trainer goal <n>` | Set uniform daily goal for all exercises |
  506. | `peon trainer goal <exercise> <n>` | Set uniform daily goal for one exercise |
  507. | `peon trainer goal <exercise> <day> <n>` | Set goal for specific day (mon, tue, etc.) |
  508. | `peon trainer goal <day> <n>` | Set all exercises for a specific day |
  509. ### Schedule vs uniform goals
  510. 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:
  511. - Setting a uniform goal removes any schedule for that exercise
  512. - Setting a day-specific goal removes any uniform goal for that exercise
  513. Days use short names: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`
  514. ```bash
  515. peon trainer goal pushups 300 # 300 pushups every day (uniform)
  516. peon trainer goal pushups mon 400 # Override: 400 on Monday (creates schedule)
  517. peon trainer goal squats sun 0 # Rest day for squats on Sunday
  518. peon trainer goal fri 150 # Light day for all exercises on Friday
  519. ```
  520. On rest days (goal=0), reminders are skipped and status shows `[REST DAY]`. You can still log reps on rest days if you want.
  521. ### Claude Code skill
  522. In Claude Code, you can log reps without leaving your conversation:
  523. ```
  524. /peon-ping-log 25 pushups
  525. /peon-ping-log 30 squats
  526. ```
  527. ### Custom voice lines
  528. Drop your own audio files into `~/.claude/hooks/peon-ping/trainer/sounds/`:
  529. ```
  530. trainer/sounds/session_start/ # session greeting ("Pushups first, code second! Zug zug!")
  531. trainer/sounds/remind/ # reminder lines ("Something need doing? YES. PUSHUPS.")
  532. trainer/sounds/log/ # acknowledgment ("Work work! Muscles getting bigger maybe!")
  533. trainer/sounds/complete/ # celebration ("Zug zug! Human finish all reps!")
  534. trainer/sounds/slacking/ # disappointment ("Peon very disappointed.")
  535. ```
  536. Update `trainer/manifest.json` to register your sound files.
  537. ## MCP server
  538. peon-ping includes an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server so any MCP-compatible AI agent can play sounds directly via tool calls — no hooks required.
  539. The key difference: **the agent chooses the sound**. Instead of automatically playing a fixed sound on every event, the agent calls `play_sound` with exactly what it wants — `duke_nukem/SonOfABitch` when a build fails, `sc_kerrigan/IReadYou` when reading files.
  540. ### Setup
  541. Add to your MCP client config (Claude Desktop, Cursor, etc.):
  542. ```json
  543. {
  544. "mcpServers": {
  545. "peon-ping": {
  546. "command": "node",
  547. "args": ["/path/to/peon-ping/mcp/peon-mcp.js"]
  548. }
  549. }
  550. }
  551. ```
  552. If installed via Homebrew: `$(brew --prefix peon-ping)/libexec/mcp/peon-mcp.js`. See [`mcp/README.md`](mcp/README.md) for full setup instructions.
  553. ### What the agent can do
  554. | Feature | Description |
  555. |---|---|
  556. | **`play_sound`** | Play one or more sounds by key (e.g. `duke_nukem/SonOfABitch`, `peon/PeonReady1`) |
  557. | **`peon-ping://catalog`** | Full pack catalog as an MCP Resource — client prefetches once, no repeated tool calls |
  558. | **`peon-ping://pack/{name}`** | Individual pack details and available sound keys |
  559. Requires Node.js 18+. Contributed by [@tag-assistant](https://github.com/tag-assistant).
  560. ## Multi-IDE Support
  561. peon-ping works with any agentic IDE that supports hooks. Adapters translate IDE-specific events to the [CESP standard](https://github.com/PeonPing/openpeon).
  562. | IDE | Status | Setup |
  563. |---|---|---|
  564. | **Claude Code** | Built-in | `curl \| bash` install handles everything |
  565. | **Amp** | Adapter | `bash adapters/amp.sh` / `powershell adapters/amp.ps1` ([setup](#amp-setup)) |
  566. | **Gemini CLI** | Adapter | Add hooks pointing to `adapters/gemini.sh` (or `.ps1` on Windows) ([setup](#gemini-cli-setup)) |
  567. | **GitHub Copilot CLI** | Built-in (auto-detect) | `install.sh` / `install.ps1` auto-registers hooks at `~/.copilot/hooks/peon-ping.json` if `~/.copilot` exists. Per-repo manual wiring also available via `adapters/copilot.sh` / `.ps1` ([setup](#github-copilot-cli-setup)) |
  568. | **OpenAI Codex** | Built-in (auto-detect) | `install.sh` / `install.ps1` auto-registers stable hooks; Unix reuses existing `hooks.json` or writes inline TOML, Windows writes inline TOML. The adapter is also available for manual wiring ([setup](#openai-codex-setup)) |
  569. | **Grok Build** | Built-in (auto-detect) | `install.sh` / `install.ps1` auto-register hooks at `~/.grok/hooks/peon-ping.json` if `~/.grok` exists. The adapter is also available for manual wiring ([setup](#grok-build-setup)) |
  570. | **Cursor** | Built-in | `curl \| bash`, `peon-ping-setup`, or Windows `install.ps1` auto-detect and register hooks. On Windows, enable **Settings → Features → Third-party skills** so Cursor loads `~/.claude/settings.json` for SessionStart/Stop sounds. |
  571. | **OpenCode** | Adapter | `bash adapters/opencode.sh` / `powershell adapters/opencode.ps1` ([setup](#opencode-setup)) |
  572. | **Kilo CLI** | Adapter | `bash adapters/kilo.sh` / `powershell adapters/kilo.ps1` ([setup](#kilo-cli-setup)) |
  573. | **Kiro** | Adapter | Add hook entries pointing to `adapters/kiro.sh` (or `.ps1`) ([setup](#kiro-setup)) |
  574. | **Windsurf** | Adapter | Add hook entries pointing to `adapters/windsurf.sh` (or `.ps1`) ([setup](#windsurf-setup)) |
  575. | **Google Antigravity** | Adapter | `bash adapters/antigravity.sh` / `powershell adapters/antigravity.ps1`. For headless / macOS LaunchAgent use, also see `bash adapters/antigravity-py.sh --install` (Python `watchdog` watcher; requires `pip3 install watchdog`). The Python watcher parses `brain/**/transcript.jsonl` for turn boundaries and `cli.log` for permission prompts, giving the same five sounds as Claude Code. Legacy `conversations/*.pb` and `*.db` sessions without a transcript fall back to a 45s idle timer (`ANTIGRAVITY_IDLE_SECONDS`). |
  576. | **Kimi Code** | Adapter | `bash adapters/kimi.sh --install` / `powershell adapters/kimi.ps1 -Install` ([setup](#kimi-code-setup)) |
  577. | **OpenClaw** | Adapter | Call `adapters/openclaw.sh <event>` (or `openclaw.ps1`) from your OpenClaw skill |
  578. | **Rovo Dev CLI** | Adapter | Auto-registered by `install.sh` if `~/.rovodev` exists, or add hooks to `~/.rovodev/config.yml` manually ([setup](#rovo-dev-cli-setup)) |
  579. | **DeepAgents** | Adapter | `bash adapters/deepagents.sh` / `powershell adapters/deepagents.ps1` ([setup](#deepagents-setup)) |
  580. | **oh-my-pi (omp)** | Adapter | `bash adapters/omp.sh` ([setup](#oh-my-pi-omp-setup)) |
  581. | **Qwen Code** | Adapter | Add hooks pointing to `adapters/qwen.sh` (or `.ps1` on Windows) ([setup](#qwen-code-setup)) |
  582. | **iFlow CLI** | Adapter | Add hooks pointing to `adapters/iflow.sh` (or `.ps1`) ([setup](#iflow-cli-setup)) |
  583. | **Trae** | Adapter | Filesystem watcher: `bash adapters/trae.sh &` / `powershell adapters/trae.ps1 -Install` ([setup](#trae-setup)) |
  584. | **Kiro IDE** | Adapter | Agent hooks in `.kiro/hooks/*.kiro.hook` calling `adapters/kiro-ide.sh` (or `.ps1`) ([setup](#kiro-ide-setup)) |
  585. | **ECA** | Adapter | Add a shell hook pointing to `adapters/eca.sh` (or `.ps1`) ([setup](#eca-setup)) |
  586. > **Windows:** All adapters have native PowerShell (`.ps1`) versions. The Windows installer (`install.ps1`) copies them to `~/.claude/hooks/peon-ping/adapters/`. Filesystem watchers (Amp, Antigravity, Kimi, Trae) use .NET `FileSystemWatcher` instead of fswatch/inotifywait — no extra dependencies needed.
  587. ### OpenAI Codex setup
  588. Codex support uses the stable Codex hooks API plus the peon-ping adapter. Both installers use `CODEX_HOME` (default `~/.codex`) and reuse an existing `hooks.json`; otherwise they add a managed block to `config.toml`. If Codex is installed later, re-run the peon-ping installer.
  589. The registered Codex events are `SessionStart`, `UserPromptSubmit`, `PermissionRequest`, `PreCompact`, `SubagentStart`, `SubagentStop`, and `Stop`. `SessionStart` is matched for `startup`, `resume`, and `clear`; Codex compaction is handled by `PreCompact`, so compact-triggered `SessionStart` is skipped. `PreToolUse`, `PostToolUse`, and `PostCompact` are intentionally not registered; `PostToolUse` is ignored by the Codex adapter because Codex does not provide a separate failure-only hook and successful tool hooks are too noisy for peon-ping.
  590. **Setup:**
  591. 1. Install the peon-ping runtime:
  592. ```bash
  593. bash "$(brew --prefix peon-ping)"/libexec/install.sh --no-rc
  594. ```
  595. Or with the standard installer:
  596. ```bash
  597. curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/install.sh | bash -s -- --no-rc
  598. ```
  599. 2. Open Codex and run `/hooks` if prompted. Codex requires non-managed command hooks to be reviewed and trusted before they run.
  600. 3. Restart Codex if it was already running during installation.
  601. On Unix and Windows, existing JSON hooks keep their format, user handlers and metadata. Updates replace only this installation's handlers, and uninstall removes them from either format. If unrelated inline TOML events and `hooks.json` already coexist, installation stops with a consolidation message instead of adding duplicate events. `peon status --verbose` detects command hooks in either file. This follows the [Codex hooks documentation](https://developers.openai.com/codex/hooks) guidance to use one representation per config layer. Legacy `notify` wiring still works as a fallback, but new installs should use the stable hooks path.
  602. ### Grok Build setup
  603. Grok Build sends camelCase hook payloads (`hookEventName`, `sessionId`, `notificationType`) with snake_case event values (`session_start`, `stop`). That is not what `peon.sh` reads natively, so peon-ping ships `adapters/grok.sh` (and `grok.ps1` on Windows) instead of pointing Grok at `peon.sh` directly.
  604. If `~/.grok` already exists, the Unix and Windows installers write `~/.grok/hooks/peon-ping.json` automatically. If you install Grok Build later, re-run the peon-ping installer.
  605. Registered events: `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `Stop`, `StopFailure`, `Notification`, `SubagentStart`, `SubagentStop`, `PostToolUseFailure`, and `PreCompact`. `PreToolUse`, `PostToolUse`, `PostCompact`, and `PermissionDenied` are left unregistered — per-tool hooks are too noisy. Session-end `Stop` fires (`reason: shutdown` or `channel_closed`) are treated as cleanup, not a completion chime. Shell failures arrive as `toolName: run_terminal_command` and are rewritten to Bash so `task.error` still plays.
  606. **Setup:**
  607. 1. Install the peon-ping runtime (`curl | bash`, Homebrew + `peon-ping-setup`, or `install.ps1`).
  608. 2. If Grok was already running, reload hooks with `/hooks` then `r`, or start a new session. Project hooks need `/hooks-trust` once; `~/.grok/hooks/` is always trusted.
  609. Grok can also scan `~/.claude/settings.json`. Those Claude hooks still call `peon.sh` with Grok's camelCase envelope, so they stay silent. The native `~/.grok/hooks/peon-ping.json` file is the one that actually plays sounds. To hide the unused Claude entries from Grok's `/hooks` list, set `[compat.claude] hooks = false` in `~/.grok/config.toml`.
  610. ### Amp setup
  611. A filesystem watcher adapter for [Amp](https://ampcode.com) (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.
  612. **Setup:**
  613. 1. Ensure peon-ping is installed (`curl -fsSL https://peonping.com/install | bash`)
  614. 2. Install `fswatch` (macOS) or `inotify-tools` (Linux):
  615. ```bash
  616. brew install fswatch # macOS
  617. sudo apt install inotify-tools # Linux
  618. ```
  619. 3. Start the watcher:
  620. ```bash
  621. bash ~/.claude/hooks/peon-ping/adapters/amp.sh # foreground
  622. bash ~/.claude/hooks/peon-ping/adapters/amp.sh & # background
  623. ```
  624. **Event mapping:**
  625. - New thread file created → Greeting sound (*"Ready to work?"*, *"Yes?"*)
  626. - Thread file stops updating + agent finished turn → Completion sound (*"Work, work."*, *"Job's done!"*)
  627. **How it works:**
  628. 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.
  629. **Environment variables:**
  630. | Variable | Default | Description |
  631. |---|---|---|
  632. | `AMP_DATA_DIR` | `~/.local/share/amp` | Amp data directory |
  633. | `AMP_THREADS_DIR` | `$AMP_DATA_DIR/threads` | Threads directory to watch |
  634. | `AMP_IDLE_SECONDS` | `1` | Seconds of no changes before emitting Stop |
  635. | `AMP_STOP_COOLDOWN` | `10` | Minimum seconds between Stop events per thread |
  636. ### GitHub Copilot CLI setup
  637. Native [GitHub Copilot CLI](https://github.com/github/copilot-cli) integration with full [CESP v1.0](https://github.com/PeonPing/openpeon) conformance.
  638. **Recommended: user-level (global) wiring — no per-repo setup.**
  639. `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.
  640. Hooks registered globally:
  641. | Event | Category | Triggered by |
  642. |---|---|---|
  643. | `SessionStart` | `session.start` | Launching `copilot` (greeting) |
  644. | `SessionEnd` | _(silent today)_ | Quitting the CLI |
  645. | `UserPromptSubmit` | `user.spam` (after 3+ rapid prompts) | Each prompt you submit |
  646. | `Stop` (= `agentStop`) | `task.complete` | Agent finishes a turn (debounced 5s) |
  647. | `Notification` | `input.required` (elicitation) | Idle, elicitation dialogs, permission popups |
  648. | `PermissionRequest` | `input.required` | Tool permission asks |
  649. | `PreToolUse` | `input.required` (only on dangerous-pattern match) | Before each tool call |
  650. | `PostToolUseFailure` | `task.error` | Tool failure |
  651. | `PreCompact` | `resource.limit` | Context compaction starting |
  652. `postToolUse` is intentionally **not** wired: peon has no `PostToolUse` handler and routing it through `Stop` floods the debounce window, swallowing real `Stop` events.
  653. **Prerequisite (Windows):** Copilot CLI hooks require [PowerShell 7+](https://github.com/PowerShell/PowerShell) (`pwsh` on `PATH`) and a permissive execution policy:
  654. ```powershell
  655. winget install Microsoft.PowerShell
  656. powershell -NoProfile -Command "Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned -Force"
  657. ```
  658. **Alternative: per-repository wiring with the adapter.**
  659. 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:
  660. ```json
  661. {
  662. "version": 1,
  663. "hooks": {
  664. "sessionStart": [
  665. {
  666. "type": "command",
  667. "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh sessionStart",
  668. "powershell": "powershell -NoProfile -File %USERPROFILE%\\.claude\\hooks\\peon-ping\\adapters\\copilot.ps1 sessionStart"
  669. }
  670. ],
  671. "agentStop": [
  672. {
  673. "type": "command",
  674. "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh agentStop",
  675. "powershell": "powershell -NoProfile -File %USERPROFILE%\\.claude\\hooks\\peon-ping\\adapters\\copilot.ps1 agentStop"
  676. }
  677. ],
  678. "postToolUseFailure": [
  679. {
  680. "type": "command",
  681. "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh postToolUseFailure",
  682. "powershell": "powershell -NoProfile -File %USERPROFILE%\\.claude\\hooks\\peon-ping\\adapters\\copilot.ps1 postToolUseFailure"
  683. }
  684. ],
  685. "notification": [
  686. {
  687. "type": "command",
  688. "bash": "bash ~/.claude/hooks/peon-ping/adapters/copilot.sh notification",
  689. "powershell": "powershell -NoProfile -File %USERPROFILE%\\.claude\\hooks\\peon-ping\\adapters\\copilot.ps1 notification"
  690. }
  691. ]
  692. }
  693. }
  694. ```
  695. 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.
  696. **Features:**
  697. - **Sound playback** via `afplay` (macOS), `pw-play`/`paplay`/`ffplay` (Linux), `MediaPlayer`/`SoundPlayer` (Windows) — same priority chain as the shell hook
  698. - **CESP event mapping** — Copilot CLI hooks map to standard CESP categories (`session.start`, `task.complete`, `task.error`, `input.required`, `user.spam`, `resource.limit`)
  699. - **Desktop notifications** — large overlay banners by default, or standard notifications
  700. - **Spam detection** — detects 3+ rapid prompts within 10 seconds, triggers `user.spam` voice lines
  701. - **Debouncing** — `Stop` events suppressed within a 5s window to prevent spam from chained tool calls
  702. ### OpenCode setup
  703. A thin TypeScript adapter for [OpenCode v1](https://opencode.ai/docs/plugins/) and [v2](https://opencode.ai/v2/docs/build/plugins) that routes events through the installed peon-ping hook. Install peon-ping first using the platform installer above.
  704. Failed OpenCode executions play `task.error`. The adapter forwards the native error message and any provided tool name; session failures are never labeled as Bash failures.
  705. **Quick install:**
  706. ```bash
  707. curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/adapters/opencode.sh | bash
  708. ```
  709. The installer copies `peon-ping.ts` to `~/.config/opencode/plugins/`, respecting `XDG_CONFIG_HOME`. On native Windows, run `powershell -NoProfile -File adapters/opencode.ps1` from a clone after installing peon-ping. The Windows adapter uses the same OpenCode discovery directory and invokes the installed `peon.ps1` directly, without Git Bash. Config, packs and playback are handled by the main peon-ping installation; use `peon config` and `peon packs` to manage them. `CLAUDE_PEON_DIR` selects a custom hook installation.
  710. One plugin supports both OpenCode API generations without install-time version detection. Independent sessions in the same project retain their native session identities. See [the event mapping and compatibility notes](docs/opencode-v2-events.md) for its API contract and validation requirements.
  711. **Features:**
  712. - **Sound playback** via `afplay` (macOS), `pw-play`/`paplay`/`ffplay` (Linux) — same priority chain as the shell hook
  713. - **CESP event mapping**: execution start, success and failure, permission requests and input forms map to standard CESP categories
  714. - **Desktop notifications** — large overlay banners by default (JXA Cocoa, visible on all screens), or standard notifications via [`terminal-notifier`](https://github.com/julienXX/terminal-notifier) / `osascript`. Fires only when the terminal is not focused.
  715. - **Terminal focus detection** — checks if your terminal app (Terminal, iTerm2, Warp, Alacritty, kitty, WezTerm, ghostty, Hyper) is frontmost via AppleScript before sending notifications
  716. - **Tab titles** — updates the terminal tab to show task status (`● project: working...` / `✓ project: done` / `✗ project: error`)
  717. - **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.
  718. - **No-repeat logic** — avoids playing the same sound twice in a row per category
  719. - **Spam detection** — detects 3+ rapid prompts within 10 seconds, triggers `user.spam` voice lines
  720. <details>
  721. <summary>🖼️ Screenshot: desktop notifications with custom peon icon</summary>
  722. ![peon-ping OpenCode notifications](https://github.com/user-attachments/assets/e433f9d1-2782-44af-a176-71875f3f532c)
  723. </details>
  724. > **Tip:** Install `terminal-notifier` (`brew install terminal-notifier`) for richer notifications with subtitle and grouping support.
  725. <details>
  726. <summary>🎨 Optional: custom peon icon for notifications</summary>
  727. 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.
  728. ```bash
  729. bash <(curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/adapters/opencode/setup-icon.sh)
  730. ```
  731. Or if installed locally (Homebrew / git clone):
  732. ```bash
  733. bash ~/.claude/hooks/peon-ping/adapters/opencode/setup-icon.sh
  734. ```
  735. 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`.
  736. > **Future:** When [jamf/Notifier](https://github.com/jamf/Notifier) ships to Homebrew ([#32](https://github.com/jamf/Notifier/issues/32)), the plugin will migrate to it — Notifier has built-in `--rebrand` support, no icon hacks needed.
  737. </details>
  738. ### Kilo CLI setup
  739. A dedicated v1 TypeScript adapter for [Kilo CLI](https://github.com/kilocode/cli) with full [CESP v1.0](https://github.com/PeonPing/openpeon) conformance. It routes events through the installed peon-ping hook. Install peon-ping first using the platform installer above.
  740. **Quick install:**
  741. ```bash
  742. curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/adapters/kilo.sh | bash
  743. ```
  744. The installer downloads the dedicated Kilo plugin to `~/.config/kilo/plugins/`, respecting `XDG_CONFIG_HOME`. Playback uses the main peon-ping installation and its configuration. Use `peon config` and `peon packs` to manage settings and packs. Native Kilo session IDs keep independent sessions separate and retain the same pack identity across later events and plugin reloads.
  745. **Features:** Same as the [OpenCode adapter](#opencode-setup) — sound playback, CESP event mapping, desktop notifications, terminal focus detection, tab titles, pack switching, no-repeat logic, and spam detection.
  746. ### Gemini CLI setup
  747. A shell adapter for **Gemini CLI** with full [CESP v1.0](https://github.com/PeonPing/openpeon) conformance.
  748. **Setup:**
  749. 1. Ensure peon-ping is installed (`curl -fsSL https://peonping.com/install | bash`)
  750. 2. Add the following hooks to your `~/.gemini/settings.json`:
  751. ```json
  752. {
  753. "hooks": {
  754. "SessionStart": [
  755. {
  756. "matcher": "startup",
  757. "hooks": [
  758. {
  759. "name": "peon-start",
  760. "type": "command",
  761. "command": "bash ~/.claude/hooks/peon-ping/adapters/gemini.sh SessionStart"
  762. }
  763. ]
  764. }
  765. ],
  766. "AfterAgent": [
  767. {
  768. "matcher": "*",
  769. "hooks": [
  770. {
  771. "name": "peon-after-agent",
  772. "type": "command",
  773. "command": "bash ~/.claude/hooks/peon-ping/adapters/gemini.sh AfterAgent"
  774. }
  775. ]
  776. }
  777. ],
  778. "AfterTool": [
  779. {
  780. "matcher": "*",
  781. "hooks": [
  782. {
  783. "name": "peon-after-tool",
  784. "type": "command",
  785. "command": "bash ~/.claude/hooks/peon-ping/adapters/gemini.sh AfterTool"
  786. }
  787. ]
  788. }
  789. ],
  790. "Notification": [
  791. {
  792. "matcher": "*",
  793. "hooks": [
  794. {
  795. "name": "peon-notification",
  796. "type": "command",
  797. "command": "bash ~/.claude/hooks/peon-ping/adapters/gemini.sh Notification"
  798. }
  799. ]
  800. }
  801. ]
  802. }
  803. }
  804. ```
  805. **Event mapping:**
  806. - `SessionStart` (startup) → Greeting sound (*"Ready to work?"*, *"Yes?"*)
  807. - `AfterAgent` → Task completion sound (*"Work, work."*, *"Job's done!"*)
  808. - `AfterTool` → Success = Silent; `tool_response.error` = Error sound (*"I can't do that."*). Legacy top-level `exit_code`/`stderr` input is also supported.
  809. - `Notification` → System notification
  810. ### Windsurf setup
  811. Add to `~/.codeium/windsurf/hooks.json` (user-level) or `.windsurf/hooks.json` (workspace-level):
  812. ```json
  813. {
  814. "hooks": {
  815. "post_cascade_response": [
  816. { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh post_cascade_response", "show_output": false }
  817. ],
  818. "pre_user_prompt": [
  819. { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh pre_user_prompt", "show_output": false }
  820. ],
  821. "post_write_code": [
  822. { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh post_write_code", "show_output": false }
  823. ],
  824. "post_run_command": [
  825. { "command": "bash ~/.claude/hooks/peon-ping/adapters/windsurf.sh post_run_command", "show_output": false }
  826. ]
  827. }
  828. }
  829. ```
  830. ### Kiro setup
  831. Create `~/.kiro/agents/peon-ping.json`:
  832. ```json
  833. {
  834. "name": "peon-ping",
  835. "hooks": {
  836. "agentSpawn": [
  837. { "command": "bash ~/.claude/hooks/peon-ping/adapters/kiro.sh" }
  838. ],
  839. "userPromptSubmit": [
  840. { "command": "bash ~/.claude/hooks/peon-ping/adapters/kiro.sh" }
  841. ],
  842. "stop": [
  843. { "command": "bash ~/.claude/hooks/peon-ping/adapters/kiro.sh" }
  844. ]
  845. }
  846. }
  847. ```
  848. `preToolUse`/`postToolUse` are intentionally excluded — they fire on every tool call and would be extremely noisy.
  849. ### Rovo Dev CLI setup
  850. A shell adapter for [Rovo Dev CLI](https://developer.atlassian.com/cloud/rovo/) (Atlassian) with full [CESP v1.0](https://github.com/PeonPing/openpeon) conformance.
  851. **Auto-setup:**
  852. If `~/.rovodev/config.yml` exists when you run `install.sh` or `peon-ping-setup`, event hooks are registered automatically.
  853. **Manual setup:**
  854. 1. Ensure peon-ping is installed (`curl -fsSL https://peonping.com/install | bash`)
  855. 2. Add to `~/.rovodev/config.yml`:
  856. ```yaml
  857. eventHooks:
  858. events:
  859. - name: on_complete
  860. commands:
  861. - command: bash ~/.claude/hooks/peon-ping/adapters/rovodev.sh on_complete
  862. - name: on_error
  863. commands:
  864. - command: bash ~/.claude/hooks/peon-ping/adapters/rovodev.sh on_error
  865. - name: on_tool_permission
  866. commands:
  867. - command: bash ~/.claude/hooks/peon-ping/adapters/rovodev.sh on_tool_permission
  868. ```
  869. 3. Restart Rovo Dev CLI for the hooks to take effect.
  870. **Event mapping:**
  871. - `on_complete` → Completion sound (*"Work, work."*, *"Job's done!"*)
  872. - `on_error` → Error sound (*"I can't do that."*, *"Son of a bitch!"*)
  873. - `on_tool_permission` → Permission prompt sound (*"Something need doing?"*, *"Hmm?"*)
  874. **Features:**
  875. - **Sound playback** via `afplay` (macOS), `pw-play`/`paplay`/`ffplay` (Linux) — same priority chain as the shell hook
  876. - **CESP event mapping** — Rovo Dev events map to standard CESP categories (`task.complete`, `task.error`, `input.required`)
  877. - **Desktop notifications** — large overlay banners by default, or standard notifications
  878. - **Debounce** — suppresses duplicate sounds from rapid completions
  879. ### Kimi Code setup
  880. A filesystem watcher adapter for [Kimi Code CLI](https://github.com/MoonshotAI/kimi-cli) (MoonshotAI). Kimi Code writes Wire Mode events to `~/.kimi/sessions/` — this adapter watches those files as a background daemon and translates events to CESP format.
  881. ```bash
  882. # Install (starts background daemon)
  883. bash ~/.claude/hooks/peon-ping/adapters/kimi.sh --install
  884. # Check status / stop
  885. bash ~/.claude/hooks/peon-ping/adapters/kimi.sh --status
  886. bash ~/.claude/hooks/peon-ping/adapters/kimi.sh --uninstall
  887. ```
  888. Requires `fswatch` (`brew install fswatch`) on macOS or `inotifywait` (`apt install inotify-tools`) on Linux. The `curl | bash` installer auto-detects Kimi Code and starts the daemon.
  889. **On macOS, `--install` registers a LaunchAgent** at `~/Library/LaunchAgents/com.peonping.kimi-adapter.plist` so the watcher auto-starts on login and auto-restarts on crash — survives reboots without re-running `--install`. Set `KIMI_NO_LAUNCHD=1` to fall back to `nohup`+pidfile (e.g. for tests). Linux always uses `nohup`+pidfile.
  890. **Kimi-only install (no Claude required):**
  891. If you don't have Claude Code and just want peon-ping for Kimi, install with `--kimi`:
  892. ```bash
  893. curl -fsSL peonping.com/install | bash -s -- --kimi
  894. ```
  895. Files land in `~/.kimi/hooks/peon-ping/` instead of `~/.claude/hooks/peon-ping/`, and no `~/.claude/` directory is created. The installer also auto-detects this layout: running it with no flags on a machine that has `~/.kimi/` but no `~/.claude/` selects `--kimi` mode automatically. The watcher daemon starts during install and re-starts on every login via the LaunchAgent.
  896. **Sharing voice packs with a Claude install:**
  897. If `~/.claude/hooks/peon-ping/packs/` already exists with packs, a `--kimi` install symlinks `~/.kimi/hooks/peon-ping/packs` at it instead of re-downloading. One pack download serves both IDEs, and `peon packs install <name>` from either side updates the shared set. State, config, and mute toggles stay isolated per install. Pass `--no-shared-packs` (or `--packs=` / `--all`) to download a separate copy.
  898. **Event mapping:**
  899. - New session → Greeting sound (*"Ready to work?"*, *"Yes?"*)
  900. - Agent finishes turn → Completion sound (*"Work, work."*, *"Job's done!"*)
  901. - Context compaction → Token limit sound
  902. - Sub-agent spawned → Sub-agent tracking
  903. ### Tool-agnostic install root (`--openpeon`)
  904. Install everything (hooks, packs, `settings.json`) under `~/.openpeon` instead of `~/.claude`:
  905. ```bash
  906. curl -fsSL peonping.com/install | bash -s -- --openpeon
  907. # Windows: powershell -File install.ps1 -OpenPeon
  908. ```
  909. Useful for an OpenPeon-branded or tool-agnostic setup: `peon.sh` auto-discovers `~/.openpeon/packs` via its packs-anchored fallback, so adapters pointed at that root work without `~/.claude`. The same reroot is also available with no flag via `CLAUDE_CONFIG_DIR=~/.openpeon bash install.sh`.
  910. ### oh-my-pi (omp) setup
  911. A native TypeScript extension for [oh-my-pi](https://github.com/can1357/oh-my-pi) (`omp`) with full [CESP v1.0](https://github.com/PeonPing/openpeon) conformance. Subscribes to omp's `ExtensionAPI` lifecycle events and routes them through `peon.sh` so omp users get every peon-ping feature: sound packs, desktop notifications, trainer reminders, mobile push, SSH/devcontainer relay, and tab-title updates.
  912. Failed omp tools play `task.error`, including non-shell tools. The adapter forwards text from the failed result and preserves the native tool name.
  913. **Quick install:**
  914. ```bash
  915. curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/adapters/omp.sh | bash
  916. ```
  917. The installer copies `peon-ping.ts` and `package.json` to `~/.omp/agent/extensions/peon-ping/`. Restart omp afterward.
  918. **Event mapping:**
  919. | omp event | peon-ping event |
  920. |----------------------------------------|-----------------------|
  921. | `session_start` | `SessionStart` |
  922. | `agent_start` | `UserPromptSubmit` |
  923. | `agent_end` (unless `willContinue`) | `Stop` |
  924. | `tool_result` with `isError: true` | `PostToolUseFailure` |
  925. | `auto_compaction_start` | `PreCompact` |
  926. | `session_shutdown` | `SessionEnd` |
  927. Tool steps within one agent loop do not trigger extra acknowledgement or completion sounds. Subagent events are skipped when omp provides `ctx.agent` (18.3.2+); older versions retain their subagent events. An `agent_end` scheduled to continue does not emit completion.
  928. **Uninstall:**
  929. ```bash
  930. curl -fsSL https://raw.githubusercontent.com/PeonPing/peon-ping/main/adapters/omp.sh | bash -s -- --uninstall
  931. ```
  932. ### Qwen Code setup
  933. A thin passthrough adapter for [Qwen Code](https://github.com/QwenLM/qwen-code) (Alibaba). Qwen Code ships a Claude-Code-style hook system — events are piped as JSON on stdin using the same PascalCase CESP names peon-ping expects — so this adapter simply re-tags the session id with a `qwen-` prefix and drops the noisy per-tool-call events.
  934. Add to `~/.qwen/settings.json`:
  935. ```json
  936. {
  937. "hooks": {
  938. "SessionStart": [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/qwen.sh" }] }],
  939. "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/qwen.sh" }] }],
  940. "Stop": [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/qwen.sh" }] }],
  941. "Notification": [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/qwen.sh" }] }],
  942. "PostToolUseFailure": [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/qwen.sh" }] }],
  943. "SessionEnd": [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/qwen.sh" }] }]
  944. }
  945. }
  946. ```
  947. On Windows, point the command at `qwen.ps1` via `powershell -NoProfile -File %USERPROFILE%\.claude\hooks\peon-ping\adapters\qwen.ps1`.
  948. ### iFlow CLI setup
  949. A passthrough adapter for [iFlow CLI](https://cli.iflow.cn) (iflow-ai). iFlow ships a Claude-Code-style hook system (PascalCase events on stdin); this adapter forwards the meaningful lifecycle events with an `iflow-` session prefix and maps a failed `PostToolUse` to `PostToolUseFailure`.
  950. Add to `~/.iflow/settings.json` (or per-project `./.iflow/settings.json`):
  951. ```json
  952. {
  953. "hooks": {
  954. "SessionStart": [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/iflow.sh" }] }],
  955. "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/iflow.sh" }] }],
  956. "Stop": [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/iflow.sh" }] }],
  957. "Notification": [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/iflow.sh" }] }],
  958. "PostToolUse": [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/iflow.sh" }] }],
  959. "SessionEnd": [{ "hooks": [{ "type": "command", "command": "bash ~/.claude/hooks/peon-ping/adapters/iflow.sh" }] }]
  960. }
  961. }
  962. ```
  963. ### Trae setup
  964. A filesystem-watcher adapter for [Trae](https://trae.ai) (ByteDance). Trae is a VS Code-derived AI IDE with no synchronous shell-hook API, so peon-ping uses the same watcher approach as Amp and Antigravity: a new session file means `SessionStart`, and an idle timer (the session file stops updating) means `Stop`.
  965. ```bash
  966. # Foreground
  967. bash ~/.claude/hooks/peon-ping/adapters/trae.sh
  968. # Background
  969. bash ~/.claude/hooks/peon-ping/adapters/trae.sh &
  970. ```
  971. On Windows: `powershell -File adapters\trae.ps1 -Install` registers a background watcher (`-Status` / `-Uninstall` to manage it).
  972. Trae's on-disk session layout varies by platform/version and isn't publicly documented, so the watched paths are environment-overridable:
  973. | Variable | Default |
  974. |---|---|
  975. | `TRAE_DATA_DIR` | `~/.trae` |
  976. | `TRAE_SESSIONS_DIR` | `$TRAE_DATA_DIR/sessions` |
  977. | `TRAE_SESSION_GLOB` | `*.json` |
  978. Requires `fswatch` (macOS: `brew install fswatch`) or `inotifywait` (Linux: `apt install inotify-tools`). Windows uses .NET `FileSystemWatcher` — no extra dependency.
  979. ### Kiro IDE setup
  980. A hook adapter for **Kiro IDE** (Amazon) — distinct from the [Kiro CLI](#kiro-setup) (`adapters/kiro.sh`). The IDE's Agent Hooks are `.kiro/hooks/*.kiro.hook` JSON files; their `then.type: runCommand` action runs a shell command with **no stdin JSON**, passing the triggering event name to the adapter as an argv argument.
  981. Create one hook file per event, e.g. `.kiro/hooks/peon-ping-stop.kiro.hook`:
  982. ```json
  983. {
  984. "version": "1.0.0",
  985. "enabled": true,
  986. "name": "peon-ping-stop",
  987. "when": { "type": "agentStop" },
  988. "then": {
  989. "type": "runCommand",
  990. "command": "bash ~/.claude/hooks/peon-ping/adapters/kiro-ide.sh agentStop"
  991. }
  992. }
  993. ```
  994. Repeat with `when.type` = `promptSubmit` (→ `UserPromptSubmit`), `preToolUse` (→ permission prompt), or `sessionStart` (→ `SessionStart`), each passing the matching event name as the command argument. `postToolUse` and file/user-triggered hooks carry no peon-relevant signal and are ignored. On Windows, point the command at `kiro-ide.ps1` via `powershell -NoProfile -File`.
  995. ### ECA setup
  996. A shell-hook adapter for [ECA](https://eca.dev) (Editor Code Assistant), an editor-agnostic LLM-agent integration. ECA pipes JSON on stdin (snake_case top-level keys) and also passes the hook type as an argv argument; this adapter maps ECA's events to CESP with a stable `eca-` session prefix derived from the ECA `db_cache_path`. Originally contributed in PeonPing/peon-ping#261, vendored first-party here.
  997. Add a shell hook to your ECA config pointing at the adapter, one per event:
  998. ```json
  999. {
  1000. "hooks": {
  1001. "sessionStart": [{ "actions": [{ "type": "shell", "command": "bash ~/.claude/hooks/peon-ping/adapters/eca.sh sessionStart" }] }],
  1002. "preRequest": [{ "actions": [{ "type": "shell", "command": "bash ~/.claude/hooks/peon-ping/adapters/eca.sh preRequest" }] }],
  1003. "postRequest": [{ "actions": [{ "type": "shell", "command": "bash ~/.claude/hooks/peon-ping/adapters/eca.sh postRequest" }] }],
  1004. "preToolCall": [{ "actions": [{ "type": "shell", "command": "bash ~/.claude/hooks/peon-ping/adapters/eca.sh preToolCall" }] }],
  1005. "sessionEnd": [{ "actions": [{ "type": "shell", "command": "bash ~/.claude/hooks/peon-ping/adapters/eca.sh sessionEnd" }] }]
  1006. }
  1007. }
  1008. ```
  1009. **Event mapping:** `sessionStart`/`chatStart` → `SessionStart`, `preRequest` → `UserPromptSubmit`, `postRequest`/`subagentPostRequest`/`postToolCall` → `Stop`, `preToolCall` → permission prompt, `sessionEnd` → `SessionEnd`.
  1010. ## Remote development (SSH / Devcontainers / Codespaces)
  1011. Coding on a remote server or inside a container? peon-ping auto-detects SSH sessions, devcontainers, and Codespaces, then routes audio and notifications through a lightweight relay running on your local machine.
  1012. ### SSH setup
  1013. 1. **On your local machine**, start the relay:
  1014. ```bash
  1015. peon relay --daemon
  1016. ```
  1017. 2. **SSH with port forwarding**:
  1018. ```bash
  1019. ssh -R 19998:localhost:19998 your-server
  1020. ```
  1021. 3. **Install peon-ping on the remote** — it auto-detects the SSH session and sends audio requests back through the forwarded port to your local relay.
  1022. That's it. Sounds play on your laptop, not the remote server.
  1023. Optional SSH routing modes:
  1024. ```bash
  1025. peon ssh-audio relay # default, always use relay
  1026. peon ssh-audio auto # try relay, fall back to local playback on SSH host
  1027. peon ssh-audio local # always play on SSH host
  1028. ```
  1029. ### Devcontainers / Codespaces
  1030. No port forwarding needed — peon-ping auto-detects `REMOTE_CONTAINERS` and `CODESPACES` environment variables and routes audio to `host.docker.internal:19998`. Just run `peon relay --daemon` on your host machine.
  1031. ### Relay commands
  1032. ```bash
  1033. peon relay # Start relay in foreground
  1034. peon relay --daemon # Start in background
  1035. peon relay --stop # Stop background relay
  1036. peon relay --status # Check if relay is running
  1037. peon relay --port=12345 # Custom port (default: 19998)
  1038. peon relay --bind=0.0.0.0 # Listen on all interfaces (less secure)
  1039. ```
  1040. Environment variables: `PEON_RELAY_PORT`, `PEON_RELAY_HOST`, `PEON_RELAY_BIND`.
  1041. If peon-ping detects an SSH or container session but can't reach the relay, it prints setup instructions on `SessionStart`.
  1042. ### Category-based API (for lightweight remote hooks)
  1043. The relay supports a category-based endpoint that handles sound selection server-side. This is useful for remote machines where peon-ping isn't installed — the remote hook only needs to send a category name, and the relay picks a random sound from the active pack.
  1044. **Endpoints:**
  1045. | Endpoint | Description |
  1046. |---|---|
  1047. | `GET /health` | Health check (returns "OK") |
  1048. | `GET /play?file=<path>` | Play a specific sound file (legacy) |
  1049. | `GET /play?category=<cat>` | Play random sound from category (recommended) |
  1050. | `POST /notify` | Send desktop notification |
  1051. **Example remote hook (`scripts/remote-hook.sh`):**
  1052. ```bash
  1053. #!/bin/bash
  1054. RELAY_URL="${PEON_RELAY_URL:-http://127.0.0.1:19998}"
  1055. EVENT=$(cat | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('hook_event_name',''))" 2>/dev/null)
  1056. case "$EVENT" in
  1057. SessionStart) CATEGORY="session.start" ;;
  1058. Stop) CATEGORY="task.complete" ;;
  1059. PermissionRequest) CATEGORY="input.required" ;;
  1060. *) exit 0 ;;
  1061. esac
  1062. curl -sf "${RELAY_URL}/play?category=${CATEGORY}" >/dev/null 2>&1 &
  1063. ```
  1064. Copy this to your remote machine and register it in `~/.claude/settings.json`:
  1065. ```json
  1066. {
  1067. "hooks": {
  1068. "SessionStart": [{"command": "bash /path/to/remote-hook.sh"}],
  1069. "Stop": [{"command": "bash /path/to/remote-hook.sh"}],
  1070. "PermissionRequest": [{"command": "bash /path/to/remote-hook.sh"}]
  1071. }
  1072. }
  1073. ```
  1074. The relay reads `config.json` on your local machine to get the active pack and volume, loads the pack's manifest, and picks a random sound while avoiding repeats.
  1075. ## Mobile notifications
  1076. Get push notifications on your phone when tasks finish or need attention — useful when you're away from your desk.
  1077. ### Quick start (ntfy.sh — free, no account needed)
  1078. 1. Install the [ntfy app](https://ntfy.sh) on your phone
  1079. 2. Subscribe to a unique topic in the app (e.g. `my-peon-notifications`)
  1080. 3. Run:
  1081. ```bash
  1082. peon mobile ntfy my-peon-notifications
  1083. ```
  1084. Also supports [Pushover](https://pushover.net) and [Telegram](https://core.telegram.org/bots):
  1085. ```bash
  1086. peon mobile pushover <user_key> <app_token>
  1087. peon mobile telegram <bot_token> <chat_id>
  1088. ```
  1089. ### Notification priority (ntfy)
  1090. By default peon-ping derives the ntfy priority from the event type (permission
  1091. prompts are `high`, routine events `default`/`low`). On iOS the lower tiers can
  1092. arrive **silently** (the banner shows but no sound plays). Set an explicit
  1093. priority to make alerts audible:
  1094. ```bash
  1095. peon mobile ntfy my-peon-notifications --priority=max
  1096. ```
  1097. You can also add a `priority` key to `mobile_notify` in `config.json`:
  1098. ```json
  1099. "mobile_notify": {
  1100. "service": "ntfy",
  1101. "topic": "my-peon-notifications",
  1102. "server": "https://ntfy.sh",
  1103. "priority": "max"
  1104. }
  1105. ```
  1106. Accepted values are ntfy priority names (`max`/`urgent`, `high`, `default`,
  1107. `low`, `min`) or numbers `1` to `5`. When set, it applies to every event,
  1108. overriding the per-event default; leave it unset to keep the original behavior.
  1109. The same value also maps to Pushover priorities for that service.
  1110. ### Mobile commands
  1111. ```bash
  1112. peon mobile on # Enable mobile notifications
  1113. peon mobile off # Disable mobile notifications
  1114. peon mobile status # Show current config
  1115. peon mobile test # Send a test notification
  1116. ```
  1117. Mobile notifications fire on every event regardless of window focus — they're independent from desktop notifications and sounds.
  1118. ## Sound packs
  1119. 165 packs across Warcraft, StarCraft, Red Alert, Portal, Zelda, Dota 2, Helldivers 2, Elder Scrolls, and more. The default install includes a curated starter set; commonly used packs include:
  1120. | Pack | Character | Sounds |
  1121. |---|---|---|
  1122. | `peon` (default) | Orc Peon (Warcraft III) | "Ready to work?", "Work, work.", "Okie dokie." |
  1123. | `peasant` | Human Peasant (Warcraft III) | "Yes, milord?", "Job's done!", "Ready, sir." |
  1124. | `sc_kerrigan` | Sarah Kerrigan (StarCraft) | "I gotcha", "What now?", "Easily amused, huh?" |
  1125. | `sc_battlecruiser` | Battlecruiser (StarCraft) | "Battlecruiser operational", "Make it happen", "Engage" |
  1126. | `glados` | GLaDOS (Portal) | "Oh, it's you.", "You monster.", "Your entire team is dead." |
  1127. **[Browse all packs with audio previews &rarr; openpeon.com/packs](https://openpeon.com/packs)**
  1128. Install all with `--all`, or switch packs anytime:
  1129. ```bash
  1130. peon packs use glados # switch to a specific pack
  1131. peon packs use --install glados # install (or update) and switch in one step
  1132. peon packs next # cycle to the next pack
  1133. peon packs list # list all installed packs
  1134. peon packs list --registry # browse all available packs
  1135. peon packs install glados,murloc # install specific packs
  1136. peon packs install --all # install every pack in the registry
  1137. ```
  1138. Want to add your own pack? See the [full guide at openpeon.com/create](https://openpeon.com/create) or [CONTRIBUTING.md](CONTRIBUTING.md).
  1139. ## Creating packs
  1140. Don't want to hand-write a manifest? `peon create` drafts a brand-new pack for you:
  1141. ```bash
  1142. peon create # interactive: prompts for name, flavor, vibe
  1143. peon create --name calm-focus --flavor sfx --vibe "soft ambient chimes, low and warm"
  1144. ```
  1145. `peon create` spawns your own Claude Code (running the `peon-ping-create-pack` skill) to write all 7 CESP categories into a draft at `~/.peon-ping/drafts/<name>/`, renders every sound through your ElevenLabs key, then opens the eval gate automatically.
  1146. **A pack doesn't exist until you approve it in the eval gate.** `peon eval <name>` starts a localhost UI where you play every sound by category, then either reroll a single sound or the whole pack with a one-line why ("too harsh, want something softer") or hit **Approve pack**. Each reroll spawns your own Claude Code again (the `peon-ping-remix` skill) to rewrite that sound's prompt honoring your caption and re-render it — `peon packs use` refuses any pack still stamped as a draft.
  1147. ```bash
  1148. peon eval <name-or-path> # open the eval gate for a draft, by name or path
  1149. ```
  1150. Approve moves the pack to `~/.peon-ping/packs/<name>` (optionally installing and switching to it on the spot). Want another round of rerolls on a pack you already approved? `peon eval <installed-pack-name>` re-drafts a copy for a fresh remix round without touching the installed original.
  1151. ### ElevenLabs key
  1152. `peon create` and rerolls both render audio through your own ElevenLabs account. Set a key once, either as an env var:
  1153. ```bash
  1154. export ELEVENLABS_API_KEY=<your key>
  1155. ```
  1156. or in `~/.config/peon-ping/credentials`:
  1157. ```
  1158. ELEVENLABS_API_KEY=<your key>
  1159. ```
  1160. Get a key at [elevenlabs.io](https://elevenlabs.io).
  1161. ## Debugging
  1162. When sounds aren't playing or notifications aren't appearing, structured debug logging helps you trace exactly what happened during a hook invocation.
  1163. ### Enabling debug logs
  1164. ```bash
  1165. peon debug on # Enable — logs written to ~/.claude/hooks/peon-ping/logs/
  1166. peon debug off # Disable
  1167. peon debug status # Show state, log directory, file count, total size
  1168. ```
  1169. You can also enable debug logging per-invocation without changing config by setting the environment variable `PEON_DEBUG=1`.
  1170. ### Reading logs
  1171. ```bash
  1172. peon logs # Last 50 lines of today's log
  1173. peon logs --last 100 # Last 100 lines across all log files
  1174. peon logs --session <ID> # Filter today's log by session ID
  1175. peon logs --session <ID> --all # Search all log files for session ID
  1176. peon logs --clear # Delete all log files (with confirmation)
  1177. ```
  1178. ### Log format
  1179. Each log line is a structured key=value record:
  1180. ```
  1181. 2026-03-26T14:32:01.042 [config] inv=a3f1 loaded=/path/to/config.json volume=0.5 pack=peon enabled=True
  1182. 2026-03-26T14:32:01.045 [event] inv=a3f1 hook_event=Stop cesp=task.complete session=abc123
  1183. 2026-03-26T14:32:01.048 [sound] inv=a3f1 file=work-work.wav label="Work, work." category=task.complete
  1184. 2026-03-26T14:32:01.120 [play] inv=a3f1 player=afplay file=work-work.wav
  1185. 2026-03-26T14:32:01.125 [notify] inv=a3f1 title="peon: done" body="Work, work."
  1186. ```
  1187. - **inv** -- unique 4-character invocation ID linking all phases of a single hook call
  1188. - **Phases**: `[config]`, `[event]`, `[sound]`, `[play]`, `[notify]` -- each represents a stage in the hook pipeline
  1189. - Values containing spaces or special characters are quoted
  1190. ### Common failure examples
  1191. | Symptom | What to look for in logs |
  1192. |---|---|
  1193. | No sound plays | `[event]` line shows `exit=early` (category disabled, paused, or debounced) |
  1194. | Wrong pack | `[config]` line shows unexpected `pack=` value -- check path_rules or rotation |
  1195. | Missing sound file | `[sound]` line shows `error=` with file path |
  1196. | Notification missing | `[notify]` line absent -- check `desktop_notifications` in config |
  1197. ### Config keys
  1198. | Key | Default | Description |
  1199. |---|---|---|
  1200. | `debug` | `false` | Enable structured debug logging |
  1201. | `debug_retention_days` | `7` | Auto-prune logs older than N days |
  1202. Logs are stored at `~/.claude/hooks/peon-ping/logs/peon-ping-YYYY-MM-DD.log` (one file per day). Old logs are automatically pruned based on `debug_retention_days` when a new day's log is created.
  1203. ## Uninstall
  1204. **macOS/Linux:**
  1205. ```bash
  1206. bash "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/hooks/peon-ping/uninstall.sh # global
  1207. bash .claude/hooks/peon-ping/uninstall.sh # project-local
  1208. ```
  1209. **Windows (PowerShell):**
  1210. ```powershell
  1211. # Standard uninstall (prompts before deleting sounds)
  1212. powershell -File "$env:USERPROFILE\.claude\hooks\peon-ping\uninstall.ps1"
  1213. # Keep sound packs (removes everything else)
  1214. powershell -File "$env:USERPROFILE\.claude\hooks\peon-ping\uninstall.ps1" -KeepSounds
  1215. ```
  1216. ## Requirements
  1217. - **macOS** — `afplay` (built-in), JXA Cocoa overlay or AppleScript for notifications
  1218. - **Linux** — one of: `pw-play`, `paplay`, `ffplay`, `mpv`, `play` (SoX), or `aplay`; `notify-send` for notifications
  1219. - **Windows** — native PowerShell with `MediaPlayer` and WinForms (no WSL required), or WSL2
  1220. - **MSYS2 / Git Bash** — `python3`, `cygpath` (built-in); audio via `ffplay`/`mpv`/`play` or PowerShell fallback
  1221. - **All platforms** — `python3` (not required for native Windows)
  1222. - **SSH/remote** — `curl` on the remote host
  1223. - **IDE** — Claude Code with hooks support, Amp, or any supported IDE via [adapters](#multi-ide-support)
  1224. ## How it works
  1225. `peon.sh` is a Claude Code hook registered for `SessionStart`, `SessionEnd`, `SubagentStart`, `Stop`, `Notification`, `PermissionRequest`, `PostToolUseFailure`, and `PreCompact` events. On each event:
  1226. 1. **Event mapping** — an embedded Python block maps the hook event to a [CESP](https://github.com/PeonPing/openpeon) sound category (`session.start`, `task.complete`, `input.required`, etc.)
  1227. 2. **Sound selection** — picks a random voice line from the active pack's manifest, avoiding repeats
  1228. 3. **Audio playback** — plays the sound asynchronously via `afplay` (macOS), PowerShell `MediaPlayer` (WSL2/MSYS2 fallback), or `pw-play`/`paplay`/`ffplay`/`mpv`/`aplay` (Linux/MSYS2)
  1229. 4. **Notifications** — updates the Terminal tab title and sends a desktop notification if the terminal isn't focused
  1230. 5. **Remote routing** — in SSH sessions, devcontainers, and Codespaces, audio and notification requests are forwarded over HTTP to a [relay server](#remote-development-ssh--devcontainers--codespaces) on your local machine
  1231. Repeated tool events exit with no child processes once the session is already working, unless a pending popup needs clearing. Meeting, Focus and tab-focus checks run only when they can suppress sound or a desktop notification.
  1232. Sound packs are downloaded from the [OpenPeon registry](https://github.com/PeonPing/registry) at install time. The official packs are hosted in [PeonPing/og-packs](https://github.com/PeonPing/og-packs). Sound files are property of their respective publishers (Blizzard, Valve, EA, etc.) and are distributed under fair use for personal notification purposes.
  1233. ## Links
  1234. - [@peonping on X](https://x.com/peonping) — updates and announcements
  1235. - [peonping.com](https://peonping.com/) — landing page
  1236. - [openpeon.com](https://openpeon.com/) — CESP spec, pack browser, [integration guide](https://openpeon.com/integrate), creation guide
  1237. - [OpenPeon registry](https://github.com/PeonPing/registry) — pack registry (GitHub Pages)
  1238. - [og-packs](https://github.com/PeonPing/og-packs) — official sound packs
  1239. - [peon-pet](https://github.com/PeonPing/peon-pet) — macOS desktop pet (orc sprite, reacts to hook events)
  1240. - [License (MIT)](LICENSE)
  1241. ## Support the project
  1242. - Venmo: [@garysheng](https://venmo.com/garysheng)
  1243. - Community Token (DYOR / have fun): Someone created a $PEON token on Base — we receive TX fees which help fund development. [`0xf4ba744229afb64e2571eef89aacec2f524e8ba3`](https://dexscreener.com/base/0xf4bA744229aFB64E2571eef89AaceC2F524e8bA3)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.