1仕組みと動作原理
本体はプロンプトではなく本物のプログラム：peon.sh がインストーラーによってホストの多様なライフサイクル hook（README に記載の SessionStart / SessionEnd / SubagentStart / Stop / Notification / PermissionRequest / PostToolUseFailure / PreCompact）として登録され、イベント発生時に再生および通知ロジックを実行します（SKILL.md は単なるラッパー）。
README.md
`peon.sh` is a Claude Code hook registered for `SessionStart`, `SessionEnd`, `SubagentStart`, `Stop`, `Notification`, `PermissionRequest`, `PostToolUseFailure`, and `PreCompact` events. On each event:
「純粋なプロンプト vs ラッパー＋実 CLI」の定義を明確化：イベントソースはホスト IDE の hook システムであり、peon.sh は 267.7KB / 7071 行の Bash メインプログラムです。
インストーラーは同じコマンドをユーザーレベルの ~/.claude/settings.json の hooks セクション（--local の場合はプロジェクトの ./.claude/settings.json）に書き込み、自身がインストールした peon.sh / notify.sh のエントリのみをクリーンアップします。
install.sh
echo "Updating Claude Code hooks in settings.json..."
同ファイルの後半にある `with open(settings_path, 'w') as f:` でディスクに書き込まれます。コメントには peon 自身の hook のみを削除し、関連ツールが登録した notify.sh は保持することが明記されています。
大半の skill は薄いプロンプト：/peon-ping-toggle はモデルに shell 経由でインストールディレクトリ配下の peon.sh toggle を呼び出させるだけで、実際のロジックはプログラム側に存在します。
skills/peon-ping-toggle/SKILL.md
bash "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/hooks/peon-ping/peon.sh toggle
同様のパターンは peon-ping-config/SKILL.md（packs list）、peon-ping-log/SKILL.md（trainer log）、および toggle の Windows 向けブランチである peon.ps1 にも見られます。
/peon-ping-use はモデル実行パスではなく hook インターセプトパスを経由：UserPromptSubmit hook がプロンプトを検知すると自身で処理して LLM を中断し、ゼロトークンで設定変更を完了します。
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.
hook は同時に Cursor の hooks.json にも書き込まれます。hook-handle-use.sh は grep 正規表現を使用して「このプロンプトが自身のコマンドであるか」を判定します。
セッション単位のボイスパック割り当て＝hook が設定ファイルと状態ファイルを直接書き換え：pack_rotation_mode を session_override に設定し、.state.json の session_packs に session→pack マッピングを書き込みます。
scripts/hook-handle-use.sh
config['pack_rotation_mode'] = 'session_override'
その後 json.dump で config.json を永続化し、state['session_packs'][session_id] に書き込みます。rename hook も同様の構造です。
ボイスパックはリポジトリ内に含まれない：インストール時に独自レジストリの一覧を読み込み、raw.githubusercontent.com からファイルを順次 <peon_dir>/packs/<pack>/ にプルして sha256 チェックサムを記録します。
scripts/pack-download.sh
PACK_BASE="https://raw.githubusercontent.com/$SOURCE_REPO/$SOURCE_REF/$SOURCE_PATH"
ダウンロード前に is_safe_pack_name / is_safe_source_repo / is_safe_source_ref / is_safe_source_path でホワイトリスト検証を実施。ダウンロード後に store_checksum が .checksums を書き込みます。リポジトリ内には trainer/sounds とデモ wav のみが存在し、packs/ はありません。
再生は各プラットフォームのネイティブツールを使用：macOS は afplay を優先（Sound Effects デバイス対応のため peon-play バイナリがインストールされている場合はそれを使用）、Linux は複数のプレイヤーを順次検出します。
peon.sh
local player="afplay"
Linux 側は pw-play → paplay → ffplay → mpv → play → aplay の順で検出。いずれも見つからない場合は WARNING を出力してインストールの必要性を提示し、サイレント障害を防ぎます。
デスクトップ通知はプラットフォームごとに実装：Linux は notify-send、macOS は terminal-notifier（未導入時は osascript にフォールバック）、Windows/WSL は PowerShell toast を使用します。
scripts/notify.sh
nohup notify-send --urgency="$urgency" $expire_time_flag $icon_flag "$title" "$msg" >/dev/null 2>&1 &
macOS ブランチは terminal-notifier を優先検出し、なければ osascript display notification にフォールバックします。Windows toast 側には独自のインジェクション緩和策（PowerShell に値を直接埋め込まず一時ファイルに書き出す）が施されています。
同一リポジトリで MCP server も提供：hook に依存せず、システムのプレイヤーを直接呼び出して指定の pack/sound を再生します。
mcp/peon-mcp.js
const child = spawn(cmd[0], cmd[1], { stdio: "ignore" });
再生コマンドはプラットフォームごとに解決されます（macOS はインストールディレクトリ内の peon-play を優先し、なければ afplay）。外部公開されるツール名は play_sound です。
SSH / devcontainer / Codespaces 環境ではローカルで音を出さず、音声および通知リクエストをローカルマシンの 19998 ポートにある relay サービスに転送します。
peon.sh
"http://${relay_host}:${relay_port}/notify" >/dev/null 2>&1 &
音声の送信パスは `curl -sf -H "X-Volume: $vol" "http://${relay_host}:${relay_port}/play?file=…"` です。relay.sh は /health ヘルスチェックを備えた対となるサーバー側プログラムです。
2コア機能
01セッションイベント発生時にキャラクターボイスを再生（デフォルトパック: peon）
02クロスプラットフォーム対応のデスクトップポップアップ通知（notify-send / terminal-notifier / osascript / PowerShell toast）
03現在のセッション専用のボイスパック割り当て（session_override ローテーションモード）
04きめ細やかな設定（音量 / ローテーション / カテゴリ / 個別効果音）
05セッションの流れに組み込まれたトレーニング記録と座りすぎ防止リマインダー
06完了通知や要介入アラートをスマートフォンにプッシュ通知（ntfy / Pushover / Telegram）
07MCP ツールとして任意の agent に音声再生機能を提供
08LLM ＋ クラウド TTS による新規ボイスパックのゼロからの生成（ElevenLabs でレンダリング）
3外部依存関係
| 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 使用） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: インストール時に peon.sh を Claude Code のイベント command hook（README 記載の8種: SessionStart / など）として登録
- 网络端点: 外部ネットワークアクセスの宣言: インストール/更新時にコアコードを取得: REPO_BASE は raw.githubusercontent.com の **main ブランチ** を指し、curl - で取得
- 本地工作目录: ファイルの読み書きと成果物の出力: ユーザーレベルの Claude 設定への書き込みと hook 登録: install.sh 内で `with open(settings_path, 'w') as f:` を実行
監査ノート： 🟠 オレンジ：評価後に使用。本 skill は2つのオレンジ基準に該当し、ソースコード上の証拠が存在します：① 認証情報と環境変数の読み取り——ELEVENLABS_API_KEY / MINIMAX_API_KEY(+GROUP_ID) / DEEPGRAM_API_KEY（ドキュメント例）/ PEON_ENV_NTFY_TOKEN、config.json からのプッシュ通知用トークンの取得、および ~/.config/peon-ping/credentials へのフォールバック読み込み；② サードパーティ製リモートパッケージおよび固定されていないインストールチェーンへの依存——インストールと自己更新が raw.githubusercontent.com の **main ブランチ** からスクリプトを取得して `curl | bash` で実行され、ボイスパックは独自レジストリと GitHub raw からダウンロードされ、アダプターは GitHub の tarball をプルします。また、インストール時に ~/.claude/settings.json、shell rc、~/.local/bin への書き込みを行い、一部アダプター向けに macOS LaunchAgent（自動起動）を登録する場合があります。レッドと判定しない理由：スクレイピング/検知回避技術がないこと、TLS 検証を無効化していないこと、sudo を要求しないこと（権限操作は chmod +x と ln -sf のみ）、ユーザー入力に対する文字ホワイトリスト検証やパッケージのパス検証を実施していること、Windows 側でメッセージ内容に対する PowerShell インジェクション緩和策が講じられていること。なお、設定駆動の実行面として、peon.sh が config の notification_title_script を `shell=True` で実行する点には留意が必要です（デフォルトは空文字列のため無効）。
5二重目の独立検証
- [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 确认默认值为空串。结论：默认关闭但机制真实存在。
6結論
最適な用途： Claude Code や Codex などのコーディングエージェントにおいて、即時の聴覚およびデスクトップフィードバックを求める開発者に最適：イベント駆動型の音声再生、クロスプラットフォーム通知、SSH/devcontainer 環境でも relay を通じた音声再生、セッションごとのキャラクターボイス切り替え、リマインダー、スマートフォンへのプッシュ通知をサポート。「複数 IDE のイベント正規化（CESP）＋ モデル実行に優先する hook」というエンジニアリング設計に関心がある開発者の参考実装としても有用です。
不向きな用途： ホスト環境のクリーンさを重視するユーザーや、変更履歴の厳密な監査性を求めるユーザーには不向き：インストール時に settings.json、shell rc、PATH を変更し、一部のアダプターでは自動起動サービスを登録します。サプライチェーンの完全な検証（固定バージョン ＋ 署名）が必須な環境にも不向き：インストールと自動更新が main ブランチの curl | bash に依存しています。設定ファイルによるコマンド実行（notification_title_script）が禁止されている環境や、ボイスパック・更新・TTS のためにインターネット接続が必要な完全オフライン環境にも適しません。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload peon-ping.tar.gz
sha256:
Option B · Copy Guide for Agent6daa61016ffad439…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 8ef376602f.