Open Island

为什么要用闭源付费软件来监控你自己的 coding agents？
开源、本地优先、原生 macOS 的 AI coding agent 伴侣应用。

中文 | English

Open Island 运行效果

--- ## Open Island 是什么？ Open Island 驻留在 Mac 的**刘海区域**（或顶部栏），为你的 AI coding agents 提供实时控制面板——会话状态、权限审批、一键跳回正确的终端。全程不打断你的工作流。可以理解为开源版的 [Vibe Island](https://vibeisland.app/)——**免费、本地运行、代码完全属于你**。 > *You don't need to pay for a product you can vibe, since you are a vibe coder.* ## 为什么选 Open Island？ - **开源** — GPL v3，fork 它、改它、发布你自己的版本 - **本地优先** — 无服务器、无遥测、无需注册。一切在你的 Mac 上运行 - **原生 macOS** — SwiftUI + AppKit，不是 Electron 套壳 - **多 Agent** — 一个界面管理 Claude Code、Codex、Cursor、Gemini CLI、OpenCode 等 - **多终端** — 一键跳回到准确的终端/IDE 会话 ## 支持的 Agents 和终端 **15 个 Agents**：Claude Code、Codex、Cursor、Gemini CLI、Grok Build、Kimi CLI、OpenCode、Pi、Oh My Pi、Qoder、Qwen Code、Factory、CodeBuddy、ZCode、Hermes Agent **15+ 终端和 IDE**：Terminal.app、Ghostty、iTerm2、WezTerm、Zellij、tmux、cmux、Kaku、VS Code、Cursor、Windsurf、Trae、Zed、JetBrains 全家桶（IDEA、WebStorm、PyCharm、GoLand、CLion、RubyMine、PhpStorm、Rider、RustRover）

完整兼容列表

### Code Agents | Agent | 状态 | 说明 | |---|---|---| | **Claude Code** | 已支持 | Hook 集成、JSONL 会话发现、status line bridge、用量追踪 | | **Codex**（CLI） | 已支持 | Hook 集成（默认 SessionStart、UserPromptSubmit、Stop；PreToolUse/PostToolUse 可解析但非默认安装）、用量追踪 | | **Codex 桌面 App** | 已支持 | Hook 集成 + app-server JSON-RPC 直连，实时获取 thread/turn 生命周期。点击 session 通过 `codex://threads/` 精确跳转到对应会话 | | **OpenCode** | 已支持 | JS 插件集成、权限/问答交互、进程检测 | | **Qoder** | 已支持 | Claude Code 分支——相同 hook 格式，配置位于 `~/.qoder/settings.json` | | **Qwen Code** | 已支持 | Claude Code 分支——相同 hook 格式，配置位于 `~/.qwen/settings.json` | | **Factory** | 已支持 | Claude Code 分支——相同 hook 格式，配置位于 `~/.factory/settings.json` | | **CodeBuddy** | 已支持 | Claude Code 分支——相同 hook 格式，配置位于 `~/.codebuddy/settings.json` | | **Cursor** | 已支持 | Hook 集成，通过 `~/.cursor/hooks.json` 配置，会话追踪，工作区跳转 | | **Gemini CLI** | 已支持 | Hook 集成，通过 `~/.gemini/settings.json` 配置，会话追踪，fire-and-forget 事件 | | **Kimi CLI** | 已支持 | Hook 集成，通过 `~/.kimi/config.toml` 的 `[[hooks]]` 数组配置，会话追踪，复用 Claude payload 协议 | | **Grok Build** | 已支持 | Hook 集成，写入 `~/.grok/hooks/open-island.json`，会话追踪与终端跳回，fire-and-forget 事件（暂无权限拦截；camelCase payload） | | **Hermes Agent** | 已支持 | Hook 集成，写入 `~/.hermes/config.yaml` 的 `hooks:` 块，会话追踪、turn 完成卡片、HITL 问题/审批卡片（clarify / pre_approval_request），fire-and-forget | | **Pi** | 已支持 | TypeScript 扩展，位于 `~/.pi/agent/extensions/open-island.ts`，会话/提示词/工具/完成事件追踪，进程检测，会话持久化，终端跳转 | | **Oh My Pi (OMP)** | 已支持 | TypeScript 扩展，位于 `~/.omp/agent/extensions/open-island.ts`，同等生命周期覆盖，适配 OMP 事件别名 | | **ZCode** | 已支持 | Hook 集成，写入 `~/.zcode/cli/config.json` 的 `hooks.events`（ZCode Desktop）。payload 与 Claude Code 兼容，复用 Claude 解码路径；仅注册生命周期事件（SessionStart、UserPromptSubmit、Stop）；进程存活跟随 ZCode.app（同 Codex.app 模式） | ### 终端和 IDE | 终端 / IDE | 支持级别 | 说明 | |---|---|---| | **Terminal.app** | 完整 | Jump-back，TTY 定位 | | **Ghostty** | 完整 | Jump-back，ID 匹配 | | **cmux** | 完整 | Jump-back，Unix socket API | | **Kaku** | 完整 | Jump-back，CLI pane 定位 | | **WezTerm** | 完整 | Jump-back，CLI pane 定位 | | **iTerm2** | 完整 | Jump-back，session ID / TTY 匹配 | | **tmux**（终端复用器） | 完整 | Jump-back，session/window/pane 定位 | | **Zellij** | 完整 | Jump-back，CLI pane/tab 定位 | | **VS Code** | 工作区 | 通过 `code` CLI 激活工作区 | | **Cursor** | 工作区 | 通过 `cursor` CLI 激活工作区 | | **Windsurf** | 工作区 | 通过 `windsurf` CLI 激活工作区 | | **Trae** | 工作区 | 通过 `trae` CLI 激活工作区 | | **Zed** | 工作区 | 识别集成终端；激活应用 / 打开项目目录 | | **JetBrains 全家桶** | 工作区 | IDEA、WebStorm、PyCharm、GoLand、CLion、RubyMine、PhpStorm、Rider、RustRover | | **Warp** | 完整支持 | 通过 SQLite pane 查找 + AX 菜单点击精准跳转到目标 tab | | **Conductor** | 应用 | 通过环境变量识别（`CONDUCTOR_SESSION_ID`）；激活 Conductor 应用 | ### 其他功能 | 功能 | 说明 | |---|---| | 刘海 / 顶部栏覆盖层 | 刘海 Mac 在刘海区域，其他 Mac 顶部居中栏 | | 设置 | Hook 安装/卸载、用量仪表盘 | | 通知模式 | 自适应高度面板，用于权限请求和会话事件 | | 通知音效 | 可配置系统音效、静音切换 | | 国际化 | English、简体中文 | | 会话发现 | 从本地 transcript 自动发现，跨启动持久化 | | 自动更新 | 基于 Sparkle 的自动更新 | | 签名公证 | DMG 打包，Apple 公证 |

## 快速开始 ### 方式一：直接下载从 [GitHub Releases](https://github.com/Octane0411/open-vibe-island/releases) 下载最新 DMG——已签名公证，开箱即用。 ### 方式二：Homebrew ```bash brew install --cask open-island ``` 后续升级用 `brew upgrade --cask open-island`。 ### 方式三：从源码构建 ```bash git clone https://github.com/Octane0411/open-vibe-island.git cd open-vibe-island open Package.swift # 在 Xcode 中打开，点击 Run ``` 首次启动时，Open Island 会自动发现活跃的 agent 会话并启动 live bridge。Hook 安装在 app 内的**设置**窗口管理。 > **系统要求**：macOS 14+、Swift 6.2、Xcode ## 工作原理 ``` Agent（Claude Code / Codex / Cursor / ...） ↓ hook 事件 OpenIslandHooks CLI（stdin → Unix socket） ↓ JSON envelope BridgeServer（app 内） ↓ 状态更新 Notch 覆盖层 UI ← 你在这里看到它 ↓ 点击跳回 → 正确的终端 / IDE ``` Hooks **fail open**——如果 Open Island 没在运行，你的 agents 不受任何影响。

架构详情

一个 Swift package 中的四个 target： | Target | 角色 | |---|---| | **OpenIslandApp** | SwiftUI + AppKit shell——菜单栏、覆盖面板、设置 | | **OpenIslandCore** | 共享库——模型、bridge 传输（Unix socket IPC）、hooks、会话持久化 | | **OpenIslandHooks** | 轻量 CLI，由 agent hooks 调用，通过 Unix socket 转发 payload | | **OpenIslandSetup** | 安装器 CLI，管理 `~/.codex/config.toml` 和 hook entries | 详见 [docs/architecture.md](docs/architecture.md)。

## 社区加入 **Discord** 参与讨论、反馈和更快的问题响应： [![Discord](https://img.shields.io/discord/1490752192368476253?style=for-the-badge&logo=discord&label=Join%20Discord&color=5865F2)](https://discord.gg/bPF2HpbCFb) 我们欢迎 issue、pull request 和新的 maintainer。详见 [CONTRIBUTING.zh-CN.md](CONTRIBUTING.zh-CN.md)。

微信群

## 通过 Code Agent 提交 Bug 遇到问题？把下面的 prompt 复制到你的 agent（Claude Code、Codex 等）中，它会自动收集环境信息并创建规范的 issue：

点击展开

``` 我在使用 Open Island (https://github.com/Octane0411/open-vibe-island) 时遇到了问题。请帮我提交一个 GitHub issue，按以下步骤操作： 1. 收集我的环境信息： - 运行 `sw_vers` 获取 macOS 版本 - 运行 `swift --version` 获取 Swift 版本 - 检查 Open Island 是否在运行：`ps aux | grep -i "open.island\|OpenIslandApp" | grep -v grep` - 获取 app 版本：`defaults read ~/Applications/Open\ Island\ Dev.app/Contents/Info.plist CFBundleShortVersionString 2>/dev/null || echo "unknown"` - 检查我当前使用的终端 2. 询问我： - 期望的行为是什么 - 实际发生了什么 - 复现步骤 3. 使用 `gh issue create` 在 GitHub 上创建 issue，格式如下： - 标题：简洁的问题概述 - 正文包含以下部分：**环境信息**、**问题描述**、**复现步骤**、**期望行为 vs 实际行为** - 如果是 bug 请添加 "bug" 标签仓库：Octane0411/open-vibe-island ```

## Star History

## Contributors

## 路线图详见 [docs/roadmap.zh-CN.md](docs/roadmap.zh-CN.md)。 --- ## Agent Parts 这部分内容是给 agents 阅读的。这是一个面向终端原生 AI coding 工作流的开源 macOS companion app。 `Open Island` 会在刘海区域或顶部栏放置一个轻量控制界面，让你可以在不中断当前 flow 的前提下观察 live coding agents、跟踪会话进度，并快速跳回正确的 terminal 上下文。 ### 为什么会有这个产品 AI coding 正在成为日常开发流程的一部分，但围绕它的控制层仍然经常意味着把你的机器交给一个闭源、收费的 app。 `Open Island` 选择了相反的路线： - 开源 - Local first，无服务器依赖 - 原生 macOS（SwiftUI + AppKit） - 适配 terminal 工作流，而不是替代它 ### 适合谁已经长期工作在 terminal 里的开发者，希望在 macOS 上和 coding agents 协作时拥有更好的上下文感，而不是在工具之间来回丢失状态。 ### Agent 集成 - **Codex CLI** — Hook 集成。Codex CLI 受管安装器默认只安装 `SessionStart`、`UserPromptSubmit` 和 `Stop`，以保持终端输出低噪声。Open Island 可以解析手动配置的 `PreToolUse` / `PostToolUse` 等更细粒度 Codex hook 事件，但这些事件不属于默认受管安装范围。Codex 文件编辑可能走内部 apply-patch 路径，因此不应把文件编辑审批描述为稳定的 `PreToolUse` 覆盖能力。从本地 rollout 文件读取 5 小时和 7 天 account usage windows。支持从设置窗口或 CLI 安装/卸载受管 hooks。 - **Codex 桌面 App** — 通过 `__CFBundleIdentifier` 识别；hook session 标记为 `isCodexAppSession`，生命周期由 `NSWorkspace.shared.runningApplications` 判断（而不是每轮对话后退出的 CLI 子进程）。除 hook 外，Open Island 还会启动自己的 `codex app-server` 子进程，通过 stdio JSON-RPC 接收实时的 `thread/started`、`turn/started`、`turn/completed`、`thread/closed` 通知。点击 session 会通过 `codex://threads/` URL scheme 精确打开对应对话。 - **Claude Code** — 基于 hook 的集成，通过 `~/.claude/settings.json` 配置。从 `~/.claude/projects/` JSONL transcript 自动发现会话。跨应用启动持久化和恢复会话。受管 status line bridge，opt-in 安装。读取缓存的 5 小时和 7 天 usage windows。 - **OpenCode** — JS 插件集成，通过 `~/.config/opencode/plugins/`。首次启动自动安装插件。接收会话生命周期、工具使用、权限和问答事件。支持权限审批和问答交互。通过 `ps` 进行进程检测。 - **Qoder** — Claude Code 分支。相同 hook 格式和事件，配置位于 `~/.qoder/settings.json`。使用 `--source qoder` 调用 hooks binary。 - **Qwen Code** — Claude Code 分支。相同 hook 格式和事件，配置位于 `~/.qwen/settings.json`。使用 `--source qwen` 调用 hooks binary。 - **Factory** — Claude Code 分支。相同 hook 格式和事件，配置位于 `~/.factory/settings.json`。使用 `--source factory` 调用 hooks binary。 - **CodeBuddy** — Claude Code 分支。相同 hook 格式和事件，配置位于 `~/.codebuddy/settings.json`。使用 `--source codebuddy` 调用 hooks binary。 - **Cursor** — 基于 hook 的集成，通过 `~/.cursor/hooks.json` 配置。接收 `beforeSubmitPrompt`、`beforeShellExecution`、`beforeMCPExecution`、`beforeReadFile`、`afterFileEdit` 和 `stop` 事件。跨应用启动持久化会话。通过 `cursor -r` 跳回工作区。使用 `--source cursor` 调用 hooks binary。 - **Gemini CLI** — 基于 hook 的集成，通过 `~/.gemini/settings.json` 配置。接收 `SessionStart`、`PreToolUse`、`PostToolUse`、`Stop` 和 `UserPromptSubmit` 事件。Fire-and-forget（无 block/deny）。使用 `--source gemini` 调用 hooks binary。 - **Kimi CLI** — 基于 hook 的集成，通过 `~/.kimi/config.toml` 的 `[[hooks]]` 数组配置（Moonshot AI）。Kimi 的 hook payload 与 Claude Code 字段兼容，Open Island 复用 Claude 解码路径，仅新增了 TOML installer。订阅 `SessionStart`、`UserPromptSubmit`、`Stop`、`Notification`、`PreToolUse`、`PostToolUse`。需要 Kimi CLI Hooks Beta。使用 `--source kimi` 调用 hooks binary。可以从设置窗口管理安装，或通过 CLI： ```sh swift run OpenIslandSetup installKimi # 把受管 [[hooks]] 条目写入 ~/.kimi/config.toml swift run OpenIslandSetup statusKimi # 查看受管 hooks 是否已安装 swift run OpenIslandSetup uninstallKimi # 移除受管条目，保留用户自定义的 [[hooks]] ``` - **Grok Build** — 基于 hook 的集成，写入 `~/.grok/hooks/open-island.json`（xAI Grok CLI / TUI）。Grok 使用 camelCase 字段（`sessionId`、`hookEventName`、`toolResult`），事件名同时接受 PascalCase 与 snake_case。Open Island 通过独立的 `--source grok` 路径完成解码与会话生命周期映射（可见性、活动状态、turn 完成、终端跳回）。受管安装注册完整支持的生命周期事件集合；工具事件为观察模式（尚未实现 PreToolUse 拦截）。仅当所有必需事件均挂载 Open Island 命令时，Settings 才显示已安装（Vibe Island 的 hooks 不计入）。可在设置窗口安装，或通过 CLI： ```sh swift run OpenIslandSetup installGrok # 写入 ~/.grok/hooks/open-island.json swift run OpenIslandSetup statusGrok # 查看受管 hooks 是否已安装 swift run OpenIslandSetup uninstallGrok # 移除 open-island.json 与 manifest ``` - **ZCode** — 基于 hook 的集成，写入 `~/.zcode/cli/config.json` 顶层的 `hooks` 块（ZCode Desktop，`ZCode.app`）。ZCode 的 hook payload 与 Claude Code 兼容（snake_case 的 `hook_event_name`、`session_id`、`cwd`，`Stop` 事件附带 `last_assistant_message`），因此 Open Island 通过独立的 `--source zcode` 入口复用 Claude 解码路径。受管的 v1 安装只注册低噪声的生命周期事件集合（`SessionStart`、`UserPromptSubmit`、`Stop`），并设置 `hooks.enabled: true`（ZCode 的配置文件 hooks 默认关闭）；同一文件中用户自建的 hook 条目会被保留。ZCode 是 Electron 应用：所有会话共享同一个应用进程，存活判定跟随运行中的应用（同 Codex.app 模式）而非逐会话 TTY 追踪，跳回时激活 ZCode。v1 暂不覆盖用量追踪与权限拦截。可在设置窗口安装，或通过 CLI： ```sh swift run OpenIslandSetup installZcode # 将受管事件写入 ~/.zcode/cli/config.json swift run OpenIslandSetup statusZcode # 查看受管 hooks 是否已安装 swift run OpenIslandSetup uninstallZcode # 移除受管条目，保留用户自定义 hooks - **Hermes Agent** — 基于 hook 的集成，写入 `~/.hermes/config.yaml` 的 `hooks:` 块（Hermes Agent CLI / gateway）。Hermes 以子进程方式运行 shell hooks（`shlex.split` + `shell=False`），JSON payload 通过 stdin 传入。Open Island 通过独立的 `--source hermes` 路径完成解码与会话生命周期映射：会话可见性、`post_llm_call` 驱动的 turn 完成卡片（`extra.user_message` / `extra.assistant_response`），以及 human-in-the-loop 拦截 —— `clarify` 工具的 `pre_tool_call` 弹出问题卡片（`.waitingForAnswer`），`pre_approval_request` 弹出审批卡片（`.waitingForApproval`）。受管安装为每个支持事件追加一条记录，并原样保留用户自建 hooks（首个 `(event, command)` 组合需要一次授权确认，或设置 `hooks_auto_accept: true`）。无 TTY 的运行（gateway、cron、CI）无法弹出该授权提示，因此新装 hooks 在这些场景下会保持未注册状态，需要先用交互式 CLI 授权一次，或设置 `hooks_auto_accept: true`（`HERMES_ACCEPT_HOOKS=1` / `--accept-hooks` 同样生效）。Fire-and-forget：hook 不向 stdout 写任何内容。可在设置窗口安装，或通过 CLI： ```sh swift run OpenIslandSetup installHermes # 写入 ~/.hermes/config.yaml 的 hooks 块 swift run OpenIslandSetup statusHermes # 查看受管 hooks 是否已安装 swift run OpenIslandSetup uninstallHermes # 移除受管条目，保留用户自建 hooks ``` ### 终端支持 - **Terminal.app**、**Ghostty**、**cmux**、**Kaku**、**WezTerm**、**iTerm2** 和 **Zellij** — 完整的 jump-back 支持，带会话附着匹配（cmux 通过 Unix socket API，Kaku/WezTerm/Zellij 通过 CLI pane 定位，iTerm2 通过 AppleScript session/TTY 探针） - **VS Code**、**VS Code Insiders**、**Cursor**、**Windsurf**、**Trae**、**Zed** — 工作区级跳转，通过对应 CLI / 激活应用（`code -r`、`cursor -r`、Zed 等） - **JetBrains 全家桶**（IntelliJ IDEA、WebStorm、PyCharm、GoLand、CLion、RubyMine、PhpStorm、Rider、RustRover） — 工作区级跳转，通过 IDE CLI launcher - **Warp** — 通过 SQLite pane 查找、pid 进程树消歧和 AX 菜单点击实现精准 tab 跳转 - **Conductor**（conductor.build） — 应用级跳转：Conductor 将每个 agent 作为无 TTY 的子进程运行，因此其会话通过 Conductor 的环境变量（`CONDUCTOR_SESSION_ID` / `__CFBundleIdentifier`）识别，而非终端；jump-back 会将 Conductor 应用带到前台 ### UI 与显示 - **刘海覆盖层** — 在有刘海的 Mac 上，island 位于刘海区域；在外接显示器或无刘海 Mac 上，降级为紧凑的顶部居中栏 - **设置** — Hook 安装/卸载、Codex/Claude 用量仪表盘、通用、显示、声音、快捷键、实验室（高级）、关于 - **通知模式** — 自适应高度的通知面板，用于权限请求和会话事件 - **通知音效** — 可配置的系统音效（默认：Bottle），支持静音切换 - **国际化** — 英文和简体中文 ### 会话管理 - Live session 可见性，支持可展开的详情行 - Session state reducer（`SessionState.apply`）作为唯一真相源 - 从本地 transcript 文件和缓存自动发现会话 - 通过 `ps`/`lsof` 进行进程发现，匹配活跃的 agent ### 架构一个 Swift package 中的四个 target： | Target | 角色 | |---|---| | **OpenIslandApp** | SwiftUI + AppKit shell — 菜单栏、覆盖面板、设置 | | **OpenIslandCore** | 共享库 — 模型、bridge 传输（Unix socket IPC）、hooks、会话持久化 | | **OpenIslandHooks** | 轻量 CLI，由 agent hooks 调用，通过 Unix socket 转发 payload | | **OpenIslandSetup** | 安装器 CLI，管理 `~/.codex/config.toml` 和 hook entries | ### 快速开始（Agent）本地构建并运行： ```bash open Package.swift ``` 构建本地 `.app` 包： ```bash zsh scripts/package-app.sh ``` 该脚本会创建 `output/package/Open Island.app` 和 `output/package/Open Island.zip`。传入 `OPEN_ISLAND_SIGN_IDENTITY` 可以签名。详见 [docs/packaging.md](docs/packaging.md)。 #### 连接 Codex 在 Xcode 中打开 package 并运行 macOS app target。启动时，app 会恢复本地缓存，扫描最近的 `~/.codex/sessions/**/rollout-*.jsonl` 文件来恢复已有 Codex sessions，然后启动 live bridge 接收新 hook events。设置窗口展示来自 `~/.codex` 的实时 Codex hook 安装状态，并可直接安装或卸载受管 hook entries。安装过程会把 helper 复制到 `~/Library/Application Support/OpenIsland/bin/OpenIslandHooks`，repo 重命名不会破坏已有 hooks。 ```bash swift build -c release --product OpenIslandHooks swift run OpenIslandSetup install swift run OpenIslandSetup status swift run OpenIslandSetup uninstall ``` #### 连接 Claude Code Claude usage 设置可在 app 设置窗口启用，保持 opt-in。bridge 会把受管 `statusLine.command` 写入 `~/.open-island/bin/open-island-statusline`，把 `rate_limits` 缓存到 `/tmp/open-island-rl.json`，不会自动覆盖已有的自定义 status line。 ### 仓库导航 - 从 [docs/index.md](docs/index.md) 开始查看文档地图。 - 阅读 [docs/quality.md](docs/quality.md) 了解质量基线和验证方式。 - 阅读 [docs/hooks.md](docs/hooks.md) 了解所有支持的 hook 事件、payload 字段和 directive 响应格式。 - 运行 `scripts/harness.sh` 进行自动化检查（文档验证、测试、构建）。 ### 系统要求 - macOS 14+ - Swift 6.2 - Xcode（用于 app target） --- ## License [GPL v3](LICENSE)