PeonPing/peon-ping

peon‑ping – AI 編碼助手的音訊與視覺提示

是什麼 – peon‑ping 是一個輕量級輔助工具，可接入 AI 驅動的編碼助手（Claude Code、GitHub Copilot、Cursor 等），讓助手能與你對話。當助手完成任務、需要權限、遇到錯誤或發生其他重要事件時，peon‑ping 會播放一段簡短的語音（通常是《魔獸》或《傳送門》等遊戲的梗圖式台詞），並顯示醒目的螢幕橫幅。目標是讓你無需持續盯著終端或 IDE，也能保持工作流程的順暢。

如何運作 – 本專案提供一個小型 CLI（peon）和一組 鈎子，支援的助手會在關鍵節點調用這些鈎子。這些鈎子會觸發 編碼事件音效包規範 (CESP)，將 task.complete 或 input.required 等事件映射到儲存在 音效包 中的音訊檔案。CLI 還管理以下功能：

• 安裝和切換音效包（包括社群貢獻的版本）。
• 控制音量、哪些事件類別發聲、是否顯示桌面疊加層。
• 透過音訊中繼守護程序，支援遠端開發（WSL2、SSH、devcontainers）。
• 可選的行動端推送通知，透過免費的 ntfy 服務實現。

主要功能

功能	你將獲得
廣泛的助手支援	為 Claude Code、Amp、GitHub Copilot、Codex、Cursor、Kiro、Qwen Code 等眾多助手提供預設適配器。
跨平台支援	macOS、Linux、Windows、WSL2、MSYS2 – 音訊播放自動適配（WPF MediaPlayer、PlaySound 或 ffmpeg 轉碼的 WAV）。
音效包	以遊戲角色（如 GLaDOS、Kerrigan）為主題的現成音效包，以及社群音效包註冊表。音效包可安裝、綁定到專案，或自動輪換。
視覺疊加層	在任意螢幕上顯示大而可設定的橫幅（霓虹、玻璃、櫻花、Jarvis），並更新終端標籤頁標題。
CLI 控制	peon toggle、peon volume 0.7、peon packs install …、peon preview 等。所有命令均支援 Tab 补全。
專注模式靜音	可選地在 macOS 的「勿擾模式」或偵測到耳機時靜音。
遠端開發支援	透過音訊中繼守護程序，將容器/SSH 會話中的聲音轉發到主機。
行動端通知	透過免費的 ntfy 服務推送通知；使用 peon mobile ntfy <topic> 設定。
可擴展設定	JSON 設定儲存在 ~/.claude/hooks/peon-ping/（或專案本地的 .claude/），並提供互動式 peon setup 導覽。

典型工作流程

1. 透過 Homebrew、提供的腳本或 Nix 安裝。
2. 執行 peon setup – 選擇音量、希望發聲的事件類別、疊加層主題等。
3. 安裝程式將適當的鈎子腳本註冊到你的 AI 編碼助手（例如，向 ~/.claude/settings.json 新增項目）。
4. 編碼過程中，助手將自動觸發聲音/疊加層：生成完成時顯示「Work complete.」，需要權限時顯示「Hmm?」等。
5. 使用 peon toggle 或 Claude Code 中的斜線命令 /peon-ping-toggle 即時靜音/取消靜音，或讓工具尊重你的 macOS 專注模式。

為何你需要它 – 如果你經常讓編碼助手在背景運行，可能會錯過它完成任務或達到限制的時刻。peon‑ping 提供了聽覺和視覺提示，讓你無需頻繁查看 IDE，也能保持專注。

---

安裝捷徑

• Homebrew（macOS/Linux）：brew install PeonPing/tap/peon-ping && peon-ping-setup
• 一鍵腳本（macOS/Linux/WSL2）：curl … | bash
• Windows PowerShell 安裝器支援 -All、-Packs、-Local 等選項。
• Nix：nix run github:PeonPing/peon-ping -- status

進一步閱讀 – 請造訪 https://peonping.com/ 查看即時示範，檢視 CESP 規範倉儲（github.com/PeonPing/openpeon），以及社群音效包註冊表（openpeon.com）。