peon-ping

PeonPing/peon-ping — AI コーディングエージェントのイベントを音声・大画面オーバーレイ・タブタイトルで知らせる（MIT）

公式サイトは peonping.com。ソースは GitHub: PeonPing/peon-ping。各 IDE のフックから共通の peon.sh 経由で再生・通知し、Coding Event Sound Pack Specification（CESP） に沿ったカテゴリでパックを差し替えられる。

14
シェルアダプタ
CESP
イベント分類
MCP
play_sound
MIT
ライセンス
解決する認知負荷

エージェントがバックグラウンドで完了・エラー・権限要求に至っても、別アプリにフォーカスがあると気づきにくい。peon-ping は 聴覚と視覚（オーバーレイ／システム通知）とターミナルタブのタイトルを組み合わせ、状態変化を短いループで取りこぼしにくくする。

flowchart LR
  E[IDE / CLI イベント] --> A[アダプタ]
  A --> P[peon.sh]
  P --> S[音声再生]
  P --> O[オーバーレイ / 通知]
  P --> T[タブタイトル]
導入経路

README に列挙されている主な方法。OS は macOS・Linux・WSL2・Windows（PowerShell）に対応。

方法コマンド / 手順備考
Homebrew（macOS）brew install peonping/tap/peon-pingtap 追加が必要な場合あり
ワンライナー（Unix）curl -fsSL https://peonping.com/install | bash公式インストーラ
Windowsirm https://peonping.com/install.ps1 | iexPowerShell
手動クローンリポジトリを取得し ./install.sh開発・カスタム向け
Nixflake / home-manager の例は README 参照installPacks でパック取得も可
WSL2 と音声: Windows 側で音声リレーを動かす手順が README にある。SSH や devcontainer では peon relay で中継する想定。
IDE アダプタ（シェル）

adapters/ 直下の *.sh がエントリ。IDE の設定からイベントごとに呼び出す。代表的な ID は次のとおり（README の Cursor 例と同様に …/adapters/<id>.sh <イベント> で指定）。

アダプタ ID想定ツール
cursorCursor
codexCodex CLI
copilotGitHub Copilot 系
windsurfWindsurf
geminiGemini CLI
kimi / kiro / kilo各種 CLI
opencode / openclaw / rovodev / deepagentsエージェント／オープンソース IDE 連携
antigravity / ampその他 README 記載の対象

Claude Code は hooks のマージが深いため、専用の home-manager オプションや ~/.claude/hooks/peon-ping/ への配置が README で案内されている。

CESP イベントと通知

README の「What you'll hear」に相当するマッピングの要約。カテゴリはパックのマニフェストと一致させる。

イベントCESP カテゴリ例（台詞の雰囲気）
セッション開始session.start作業開始の合図
タスク完了task.complete完了の合図
タスク受理（任意）task.acknowledge既定ではオフになりがち
権限・入力待ちinput.requiredユーザー操作が必要
ツール／コマンド失敗task.errorエラー系ボイス
レート・トークン上限resource.limitリソース枯渇
短時間に多発プロンプトuser.spamスパム検知

macOS では JXA ベースの大画面オーバーレイ、テーマ（neon / glass / sakura / jarvis など）、通知位置・自動消去が peon setup や CLI で切り替え可能。標準通知モードでは terminal-notifier 等との連携も README に記載。

CLI と設定

実行ファイル名は peon。ミュートは /peon-ping-toggle（Claude Code）または peon toggle。対話セットアップは peon setup。設定はグローバルなら $CLAUDE_CONFIG_DIR/hooks/peon-ping/config.json（省略時は ~/.claude/hooks/peon-ping/config.json）、ローカルインストール時は ./.claude/hooks/peon-ping/config.json。

# 例: 音量と通知の確認
peon status
peon volume 0.7
peon notifications overlay

独立した 3 スイッチ: enabled（音声マスタ）、desktop_notifications（デスクトップ）、mobile_notify.enabled（モバイル push）。README の表どおり、音だけ・通知だけといった組み合わせが可能。

MCP サーバ

リポジトリ内の mcp/ に Node 製サーバがある。エージェントから play_sound でキー（例: duke_nukem/Groovy）を指定して再生。カタログは MCP Resource として公開され、モデルが一覧を一度読める設計。

MCP 機能役割
Tool play_soundsound または sounds 配列で再生
Resource peon-ping://catalog全パック・全サウンドのカタログ
Resource peon-ping://pack/{name}指定パックのカテゴリ別一覧

要件は Node.js 18+ と、ホストに peon-ping が入っていること。MCP クライアントの設定では node と peon-mcp.js へのパス（クローンしたプロジェクト内の絶対パス、またはインストール先）を指定する。

Claude Code 向けスキル

リポジトリの skills/ に 5 ディレクトリ。トグル・設定・セッション名・ログ・利用ガイドをエージェントが読み取れる。

外部