erha19/ping-island

A Dynamic Island-style command center for managing all your AI coding agents on macOS.

Ping Island – macOS 的 AI 程式碼編寫工作階段監控器

這是什麼 – 一款原生的 macOS 選單列（與凹口）應用程式，能夠監控多個 AI 程式碼編寫助手（Claude、Codex、Gemini CLI、Hermes、Pi、Qwen、Kimi、OpenClaw、Cursor、Qoder、GitHub Copilot 等）的活動。當助手需要您的注意時——例如工具核准請求、後續問題或完成通知——應用程式會從選單列或螢幕凹口展開，顯示相關情境，讓您無需尋找發起請求的終端機或 IDE 分頁即可採取行動。

快速開始

步驟	指令 / 動作
安裝	`brew install --cask ping-island` （或從網站下載 DMG）
執行	從應用程式打開 Ping Island.app 並授予要求的輔助使用 / Apple 事件權限
連接客戶端	啟動任何受支援的 AI 程式碼編寫客戶端（例如 Claude、Codex、Gemini CLI）。客戶端的掛鉤檔案會自動指向隨附的 `PingIslandBridge`，它會將事件轉發至應用程式
互動	當請求出現時，在凹口 UI 中直接核准/拒絕或輸入回覆；點擊「返回」按鈕以跳回發起請求的 iTerm2、終端機、tmux 窗格或 IDE 視窗

核心功能

注意力優先的 UI – 保持隱藏直到 AI 工作階段需要輸入，然後從選單列或螢幕凹口彈出。
一鍵返回 – 跳轉到生成請求的確切終端機/IDE 視窗。
Claude Code 自動核准 – 可選擇針對每個工作階段進行自動核准，以阻止 Claude 在每次權限請求時暫停。
遠端主機支援 – 輕量級的 PingIslandBridge 可以安裝在 Linux SSH 主機上；橋接器會將遠端掛鉤事件轉發回 macOS UI。
多代理涵蓋範圍 – 在單一窗格中追蹤 12 個以上的代理與外掛程式（Claude、Codex、Gemini CLI、Antigravity CLI、Hermes、Pi、Qwen、Kimi、OpenClaw、OpenCode、Cursor、Qoder 家族、GitHub Copilot 等）。
可自訂的體驗 – 三種內建視覺主題（原生、macOS、Pixel）和三種音效模式（系統音效、內建 8 位元、使用者提供的音效包）。每個客戶端都可以有自己的動畫吉祥物。
夥伴分離 (v0.5+) – 將活動中的吉祥物從凹口拖出，以便在螢幕上保留一個浮動的陪伴角色。

受支援的客戶端（入口 → 焦點路徑）

客戶端	應用程式如何接收事件	如何返回焦點
Claude Code	透過 `PingIslandBridge` 的 Claude 相容掛鉤檔案	Terminal.app、iTerm2、Ghostty、tmux 或 IDE 終端機
Codex (CLI + app‑server)	Codex CLI 掛鉤 + 到 Codex app‑server 的即時 websocket	Codex 應用程式、終端機、tmux、IDE
Gemini CLI	`~/.gemini/settings.json` 中的掛鉤項目	任何終端機主機
Antigravity CLI	`~/.gemini/antigravity-cli/plugins/ping‑island/` 下生成的的外掛程式	終端機主機與遠端 SSH
Hermes Agent	`~/.hermes/plugins/ping_island/` 中的外掛程式掛鉤	Hermes CLI 終端機
Pi Agent	`~/.pi/agent/extensions/ping_island/` 下的擴充功能	Pi 終端機主機
Qwen Code	`~/.qwen/settings.json` 中的掛鉤檔案	終端機主機與遠端 SSH
Kimi CLI	`~/.kimi/config.toml` 中的 `[[hooks]]` 項目	終端機主機
OpenClaw	受管理的內部掛鉤 + 本機轉錄補填	OpenClaw 終端機
OpenCode	`~/.config/opencode/plugins/` 下的外掛程式檔案	OpenCode 應用程式與終端機
Cursor	Claude 相容掛鉤 + 可選的 VS Code 焦點擴充功能	Cursor 專案視窗與終端機
Qoder 家族 (IDE / CLI)	`~/.qoder*` 中的掛鉤設定檔	Qoder IDE 視窗、終端機或 VS Code 相容擴充功能
CodeBuddy / WorkBuddy	受管理的掛鉤 + 可選的 VS Code 焦點擴充功能	應用程式視窗、終端機、IDE
GitHub Copilot	Copilot 掛鉤協定	相容的終端機主機

運作方式（高階流程）

AI client (Claude, Codex, Gemini …) → hook or app‑server event
    → Ping Island monitor (normalizes different payloads)
        → SessionStore (keeps per‑client session state)
            → SessionMonitor / NotchViewModel
                → UI: notch bar, session list, hover preview, completion popup

監控器將每個客戶端的原生掛鉤格式轉換為通用的內部模型。
SessionStore 聚合事件（工具核准、使用者提示、完成），以便 UI 可以顯示簡潔的時間軸。
NotchViewModel 驅動駐留在選單列/凹口中的精簡 UI，並根據需求展開。
對於遠端 Linux 主機，PingIslandBridge 二進位檔案透過 SSH 執行，重寫遠端掛鉤以指向回 Mac，並轉發遠端 Codex app‑server 串流。

建置 / 測試（如果您想動手修改）

# Clone and build (requires macOS 14+ and Xcode with Swift 6.1)
git clone https://github.com/erha19/ping-island.git && cd ping-island
xcodebuild -project PingIsland.xcodeproj -scheme PingIsland -configuration Release build

# Package an unsigned DMG for local testing
./scripts/package-unsigned.sh

# Run the full test suite
./scripts/test.sh   # runs Swift package tests and Xcode unit/UI tests

CI 腳本也會產生已簽署、已公證的發行版本和 Linux PingIslandBridge 資產。

設定快照

類別	您可以調整的內容
一般	登入時啟動、預設行為
顯示	使用哪個凹口（如果有的話）、位置
吉祥物	針對每個客戶端的吉祥物覆寫、動畫狀態
音效	選擇體驗主題，選取系統音效或匯入自訂音效包

誰可能需要這個？

使用多個 AI 程式碼編寫助手的開發者，且經常收到權限或澄清提示。
在配備凹口的 Mac 上工作的人，他們偏好微小、永遠可見的 UI 而不是切換視窗。
遠端開發者，他們透過 SSH 在 Linux 伺服器上執行 AI 代理，並且仍然希望有本機可見性。
喜歡視覺自訂的進階使用者 – 吉祥物、復古像素主題、自訂音效。

授權與社群

授權： Apache 2.0（寬鬆，允許商業使用）。
貢獻者： 儲存庫列出了一份 CONTRIBUTORS.md，並提供了用於新增體驗主題或支援其他 AI 客戶端的文件。
隱私： 頁首連結了一份簡短的隱私權政策；該應用程式僅處理本機掛鉤事件，不會將資料發送到其他地方。

總結： Ping Island 是一款專注的開源 macOS 工具程式，將 AI 程式碼編寫助手的通知帶入選單列/凹口，讓您在保持對核准和後續問題的完全控制之餘，仍能專注於工作流程。