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)
运行	从 Applications 中打开 Ping Island.app，并授予所需的辅助功能 / Apple-Events 权限
连接客户端	启动任意受支持的 AI 编码客户端（如 Claude、Codex、Gemini CLI）。客户端的钩子文件将自动指向内置的 `PingIslandBridge`，该组件会将事件转发给应用
交互	当请求出现时，直接在凹口界面中批准/拒绝或输入回复；点击“返回”按钮即可跳回原始的 iTerm2、Terminal、tmux 窗口或 IDE 窗口

核心功能

以注意力为中心的 UI – 仅在 AI 会话需要输入时才显示，随后从菜单栏或屏幕凹口弹出。
一键返回 – 跳转到生成请求的精确终端/IDE 窗口。
Claude Code 的自动批准 – 可选的会话级自动批准，防止 Claude 在每次权限请求时暂停。
远程主机支持 – 可在 Linux SSH 主机上安装轻量级的 PingIslandBridge；该桥接组件将远程钩子事件转发回 macOS 界面。
多代理覆盖 – 在单个面板中跟踪 12+ 个代理和插件（Claude、Codex、Gemini CLI、Antigravity CLI、Hermes、Pi、Qwen、Kimi、OpenClaw、OpenCode、Cursor、Qoder 系列、GitHub Copilot 等）。
可自定义体验 – 内置三种视觉主题（原生、macOS、像素）和三种声音模式（系统声音、内置 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 客户端（Claude、Codex、Gemini …） → 钩子或应用服务器事件
    → Ping Island 监控器（标准化不同格式的负载）
        → SessionStore（保存每个客户端的会话状态）
            → SessionMonitor / NotchViewModel
                → UI：凹口栏、会话列表、悬停预览、完成弹窗

监控器将每个客户端的原生钩子格式转换为统一的内部模型。
SessionStore 聚合事件（工具批准、用户提示、完成等），使 UI 能够展示简洁的时间线。
NotchViewModel 驱动位于菜单栏/凹口的紧凑 UI，按需展开。
对于远程 Linux 主机，PingIslandBridge 二进制文件通过 SSH 运行，重写远程钩子使其指向 Mac，并转发远程 Codex 应用服务器流。

构建 / 测试（如果你想动手尝试）

# 克隆并构建（需要 macOS 14+ 和带有 Swift 6.1 的 Xcode）
git clone https://github.com/erha19/ping-island.git && cd ping-island
xcodebuild -project PingIsland.xcodeproj -scheme PingIsland -configuration Release build

# 为本地测试打包一个未签名的 DMG
./scripts/package-unsigned.sh

# 运行完整测试套件
./scripts/test.sh   # 运行 Swift 包测试和 Xcode 单元/UI 测试

CI 脚本还会生成签名、公证的发布版本和一个 Linux PingIslandBridge 资产。

设置快照

类别	可调整内容
通用	登录时启动，默认行为
显示	使用哪个凹口（如有），位置
吉祥物	每个客户端的吉祥物覆盖，动画状态
声音	选择体验主题，选择系统声音或导入自定义音效包

哪些人可能会需要它？

使用多个 AI 编码助手的开发者，并频繁收到权限或澄清提示。
在配备凹口的 Mac 上工作的人，更倾向于使用一个微小、始终可见的 UI，而不是切换窗口。
远程开发者，通过 SSH 在 Linux 服务器上运行 AI 代理，但仍希望获得本地可见性。
喜欢视觉自定义的高级用户——吉祥物、复古像素主题、自定义音频。

许可与社区

许可：Apache 2.0（宽松许可，允许商业使用）。
贡献者：仓库列出了 CONTRIBUTORS.md，并提供文档以添加新的体验主题或支持额外的 AI 客户端。
隐私：标题中链接了简短的隐私政策；该应用仅处理本地钩子事件，不会将数据发送到其他地方。

总结：Ping Island 是一款专注、开源的 macOS 工具，将 AI 编码助手的通知带入菜单栏/凹口，让你在保持工作流的同时，仍能完全掌控授权和后续问题。