Workflow & Core Tools · PeonPing/peon-ping
peon-ping
Set which voice pack (character voice) plays for the current chat session. Automatically enables session_override rotation mode if not already set. Use when user wants a specific character voice like GLaDOS, Peon, or Kerrigan for this conversation.
L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit
Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.
1How It Works & Mechanism
The core is an actual program rather than prompts: peon.sh is registered by the installer as multiple lifecycle hooks for the host (README lists SessionStart / SessionEnd / SubagentStart / Stop / Notification / PermissionRequest / PostToolUseFailure / PreCompact), executing playback and notification logic upon incoming events (SKILL.md serves merely as a shell).
README.md
`peon.sh` is a Claude Code hook registered for `SessionStart`, `SessionEnd`, `SubagentStart`, `Stop`, `Notification`, `PermissionRequest`, `PostToolUseFailure`, and `PreCompact` events. On each event:
This strictly clarifies 'pure prompt vs. wrapper + real CLI': the event source is the host IDE's hook system, and peon.sh is a 267.7KB / 7071-line Bash main program.
The installer writes the same command into the hooks section of the user-level ~/.claude/settings.json (or the project's ./.claude/settings.json if --local is used), and only cleans up the peon.sh / notify.sh entries that it installed itself.
install.sh
echo "Updating Claude Code hooks in settings.json..."
Persisted via `with open(settings_path, 'w') as f:` later in the same file; comments specify that only peon's own hooks are removed, keeping notify.sh registered by sibling tools intact.
Most skills are thin prompts: /peon-ping-toggle directs the model to invoke peon.sh toggle under the installation directory via the shell, with the actual logic residing inside the program.
skills/peon-ping-toggle/SKILL.md
bash "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/hooks/peon-ping/peon.sh toggle
The same pattern appears in peon-ping-config/SKILL.md (packs list), peon-ping-log/SKILL.md (trainer log), and peon.ps1, the Windows branch of toggle.
/peon-ping-use takes the hook interception path rather than the model path: the UserPromptSubmit hook reads the prompt, handles it internally, and halts the LLM, completing configuration updates with zero tokens.
skills/peon-ping-use/SKILL.md
The hook scripts (`scripts/hook-handle-use.sh` and `scripts/hook-handle-use.ps1`) do all the work - this SKILL.md file exists solely for discoverability in the `/` command autocomplete menu.
The hook is simultaneously written into Cursor's hooks.json; hook-handle-use.sh uses a grep regex to determine whether 'this prompt is my command'.
Session-level voice pack assignment equals direct rewriting of config and state files by hooks: sets pack_rotation_mode to session_override and writes the session→pack mapping into session_packs in .state.json.
scripts/hook-handle-use.sh
config['pack_rotation_mode'] = 'session_override'
Followed by a json.dump flush to config.json and writing state['session_packs'][session_id]; the rename hook works identically.
Voice packs are not stored in the repository: during installation, it reads a custom registry manifest and pulls files one by one from raw.githubusercontent.com into <peon_dir>/packs/<pack>/, recording sha256 checksums.
scripts/pack-download.sh
PACK_BASE="https://raw.githubusercontent.com/$SOURCE_REPO/$SOURCE_REF/$SOURCE_PATH"
Whitelisting is enforced before download via is_safe_pack_name / is_safe_source_repo / is_safe_source_ref / is_safe_source_path; store_checksum writes .checksums after download. The repo only contains trainer/sounds and demo wav files, no packs/.
Playback uses platform-native utilities: macOS prefers afplay (or switches to the peon-play binary if installed to support Sound Effects devices), while Linux probes multiple players sequentially.
peon.sh
local player="afplay"
Linux probes in the order of pw-play → paplay → ffplay → mpv → play → aplay; if none are found, it prints a WARNING prompting to install one, rather than failing silently.
Desktop notifications are implemented per platform: Linux uses notify-send, macOS uses terminal-notifier (falling back to osascript if absent), and Windows/WSL uses PowerShell toasts.
scripts/notify.sh
nohup notify-send --urgency="$urgency" $expire_time_flag $icon_flag "$title" "$msg" >/dev/null 2>&1 &
The macOS branch probes terminal-notifier before falling back to osascript display notification; the Windows toast branch includes dedicated injection mitigation (writing messages to temporary files instead of interpolating them into PowerShell).
The same repository also provides an MCP server: it spawns system players directly to play designated pack/sound assets without relying on hooks.
mcp/peon-mcp.js
const child = spawn(cmd[0], cmd[1], { stdio: "ignore" });
Playback commands are resolved per platform (macOS prioritizes peon-play in the installation directory, falling back to afplay); the externally exposed tool name is play_sound.
In SSH / devcontainer / Codespaces scenarios, sound is not emitted locally; instead, audio and notification requests are sent to a relay service on host port 19998.
peon.sh
"http://${relay_host}:${relay_port}/notify" >/dev/null 2>&1 &
The audio path is `curl -sf -H "X-Volume: $vol" "http://${relay_host}:${relay_port}/play?file=…"`; relay.sh is the companion server-side daemon with a /health probe.
2Core Capabilities
01Play character voice packs on session events (peon default pack)
02Cross-platform desktop popup notifications (notify-send / terminal-notifier / osascript / PowerShell toast)
03Assign a dedicated voice pack to the current session (session_override rotation mode)
04Fine-grained configuration (volume / rotation / categories / individual sound effects)
05Habit tracking and sedentary reminders embedded directly in the session flow
06Push completion and human intervention alerts to mobile devices (ntfy / Pushover / Telegram)
07Provide playback capabilities to any agent as an MCP tool
08Generate new voice packs from scratch using LLMs + cloud TTS (rendered with ElevenLabs)
3External Dependencies
| Kind | Dependency / Endpoint |
|---|---|
| network | GitHub raw（核心文件与语音包下载，main 分支未 pin） |
| network | 语音包文件下载基址（按 registry 的 source_repo/ref/path 拼接） |
| network | 自建语音包 registry 清单 |
| network | GitHub 仓库 tarball（部分适配器安装包） |
| api | ElevenLabs 声音生成 / TTS（xi-api-key 头鉴权） |
| api | MiniMax 语音合成（T2A v2，两个地区端点） |
| api | ntfy 手机推送（服务器可在配置中覆盖） |
| api | Pushover 推送 |
| api | Telegram Bot 推送 |
| network | 本机音频 / 通知 relay |
| cli | 系统通知 / 播放 / 编译依赖 |
| package | MCP SDK（Node，供 mcp/peon-mcp.js 使用） |
4Recommended Governance & Evidence
Suggested Controls for Safe Operation
For Agent Runtime
Graded/per-use authorization, sandbox recommended
For Administrators
Approval workflow, rollback support, full audit
Evidence & Triggers (File Paths & Excerpts)
- scripts/: Local script or command execution: Installation registers peon.sh as Claude Code event command hooks (the 8 categories listed in the README: SessionStart /
- 网络端点: Declared external network access: Core code fetched during install/update: REPO_BASE points to the **main branch** on raw.githubusercontent.com, installed via curl -
- 本地工作目录: File I/O and artifact output: Writes user-level Claude settings and registers hooks: install.sh uses `with open(settings_path, 'w') as f:`
Audit Notes: 🟠 Orange: Use after evaluation. This skill triggers two orange criteria with source code evidence: ① Credential and environment variable reads—ELEVENLABS_API_KEY / MINIMAX_API_KEY(+GROUP_ID) / DEEPGRAM_API_KEY (documentation examples) / PEON_ENV_NTFY_TOKEN, mobile push tokens read from config.json, and a fallback to ~/.config/peon-ping/credentials; ② Dependence on third-party remote packages and unpinned installation chains—both installation and self-updating pull scripts from raw.githubusercontent.com on the **main branch** and execute via `curl | bash`, voice packs are downloaded from a custom registry + GitHub raw, and adapters pull GitHub tarballs; the installation writes to ~/.claude/settings.json, shell rc, and ~/.local/bin, and can register macOS LaunchAgents (auto-start) for some adapters. It avoids a Red rating because it lacks anti-scraping/anti-detection evasion, does not disable TLS verification, requires no sudo (privileged actions are limited to chmod +x and ln -sf), enforces character whitelists on user inputs, validates paths in pack manifests, and implements dedicated PowerShell injection mitigation on Windows. An additional consideration is the config-driven execution surface: peon.sh executes notification_title_script from config with `shell=True` (empty by default, hence disabled).
5Second-Pass Verification
- [ok] skill.path 的选取（skills/peon-ping-use） — 重读仓库根目录（无 SKILL.md、无 plugin.json/marketplace.json）、glob **/SKILL.md（恰 7 个，全在 skills/peon-ping-*/）、glob **/plugin.json 与 **/marketplace.json（零命中）、以及 docs/public/llms.txt 与 README 对技能的分组排序。结论：展示名是产品级/仓库级，没有单一插件入口声明，必须主观择一；选 peon-ping-use（frontmatter 带 license: MIT 与 metadata.author: PeonPing，且是会话级语音包切换的主实现）。七个技能的 name/description 原文均已取证，可零成本改选。
- [discrepancy] 仓库 7 个 SKILL.md 与安装器 6 个的矛盾 — 重读 install.sh 的 install_skill 调用段（仅 6 个：toggle/config/use/log/remix/create-pack）与 install.ps1 的技能数组（同样 6 个，无 rename）。结论：peon-ping-rename 的 SKILL.md 不会被装到用户目录，只有它的 hook 脚本被单独下载——宣称 7 个、落地 6 个。
- [ok] external_deps：raw.githubusercontent.com 系列调用点 — 分别重读 install.sh 的 REPO_BASE 定义与下载段、pack-download.sh 的 PACK_BASE 拼接、peon.sh 的自更新与 VERSION 探测、adapters/omp.sh 与 adapters/kilo.sh。全部为明文 HTTPS 拉取，**无 pin、无签名校验**（语音包的 sha256 基线也来自同一来源，故不能防上游作恶）。
- [ok] external_deps：自建 registry 与 peon.sh 内的 urllib 拉取 — 重读 install.sh 的 REGISTRY_URL 常量，并在 peon.sh 检索 urllib.request.urlopen 命中两处同一 URL；另 pack-download.sh 亦有同域请求。属自建静态清单，与包文件所在 GitHub raw 分离。
- [ok] security：hooks 写进了哪里、注册了哪些事件 — 重读 install.sh 的 hook 安装段：HOOK_CMD 指向 $GLOBAL_BASE/hooks/peon-ping/peon.sh，settings.json 两次被以 'w' 模式改写；另确认 UserPromptSubmit 的两个 hook 分别指向 hook-handle-use.sh 与 hook-handle-rename.sh。README 侧 11 类事件清单与之吻合。
- [ok] security：是否提权 / 是否碰系统目录 — 对 install.sh、peon.sh、relay.sh、scripts/、adapters/ 检索 sudo：零命中；重读 install.sh 的 chmod 与软链段确认权限动作只有 chmod +x，写入目标全部在 $HOME 之下（~/.claude、~/.local/bin、~/.zshrc、~/.bashrc、~/.config/fish、~/Library/LaunchAgents）。
- [ok] security：凭据读取清单 — 重读 pack-render.py（env + 两处文件回退 + xi-api-key 头）、tts-minimax.sh/.ps1（MINIMAX_API_KEY / GROUP_ID）、peon.sh 的手机推送凭据读段。结论：本地配置/环境变量 → 明文 HTTPS 出站到用户自选的第三方服务，无第三方中转、不上传至作者域名。
- [ok] security：配置驱动的 shell 执行 — 在 peon.sh 检索 notification_title_script 命中取值与执行两处，重读该段确认 `_sp.run(_script, shell=True, capture_output=True, text=True, timeout=2, env=_env)`；又重读 config.json 确认默认值为空串。结论：默认关闭但机制真实存在。
6Verdict & Scenarios
Best for: Ideal for developers seeking immediate auditory and desktop feedback in coding agents like Claude Code or Codex: event-driven playback, cross-platform notifications, relay-supported remote audio in SSH/devcontainers, session-specific character voice switching, habit reminders, and mobile push alerts. Also great as a reference for engineering designs such as 'multi-IDE event standardization (CESP) + hook prioritization over model execution' via its adapters and hooks.
Not for: Not suitable for users sensitive to host environment cleanliness or requiring an auditable change stream: alters settings.json, shell rc, and PATH during installation, and may register launch-at-boot services for certain adapters. Not suitable for environments requiring verifiable supply chains (pinned versions + signatures): installation and self-updating rely on curl | bash from the main branch. Not suitable for environments prohibiting command execution triggered by configuration files (notification_title_script). Not suitable for completely air-gapped machines, as voice packs, updates, and optional TTS require internet access.
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload peon-ping.tar.gz
sha256:
Option B · Copy Guide for Agent6daa61016ffad439…Agents automatically download and verify mirrors from this JSON guide.
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 8ef376602f.