Harbor Light

给 Coding Agent 装上一盏状态灯。不用反复切回 Codex 或 Cursor，也能一眼看出 Agent 正在工作、等待确认，还是已经完成。

Harbor Light 把 Codex 和 Cursor 的实时状态变成可跨屏拖动的红黄绿悬浮窗。它按软件、项目和对话分别记账，多个任务可以同时亮灯，不会互相覆盖。当前版本 0.1.0，支持 macOS 12+ 与 Windows 10/11（x64 / ARM64）。核心用 Rust 写成，不依赖 Python 或 Swift 运行时。源码在 harbor-light。

它做什么

一眼识别状态：黄灯工作、红灯等待、绿灯完成，不用切窗口确认进度。
多任务分开记：同时看 Codex、Cursor 的多个项目和对话。一个任务完成，不会盖住另一个仍在跑的任务。
轻量悬浮窗：始终置顶、不抢焦点，可跨屏拖动并记住位置。
装好就能用：自动合并用户级 Codex / Cursor Hooks，并配置登录自启动。

灯怎么看

状态	含义	悬浮窗
黄灯	Agent 正在思考或执行	呼吸
绿灯	当前任务已经完成	弹出，大约 3 秒后回到空闲
红灯	需要审批，或要处理错误	急促闪烁
红灯 + 黄灯	一个任务在等待，其他任务仍在执行	同步急促闪烁
空闲	当前没有活动任务	三灯低亮

拖动黑色胶囊即可跨屏摆放，窗口会记住位置。显示器拔掉以后，如果窗口留在屏幕外，会自动回到主屏右上方。macOS 从菜单栏图标打开菜单，Windows 右键系统托盘。两边都能看当前状态、重新安装 Hooks 或退出。macOS 菜单还可以切换开机自启。

怎么工作

Codex 和 Cursor 的 Hooks 把事件交给各自的适配器，写成 ~/.harbor-light/activities/ 下按软件分开的活动文件。Codex 还会扫描 rollout JSONL 作为兜底。悬浮窗读这些文件，聚合成一盏灯。

同时在发生的事	展示
有等待，同时还有别的对话在工作	红黄同步闪烁
只有等待	红灯闪烁
没有等待，但还有工作	黄灯呼吸
没有活动，但有完成且还没超时	绿灯弹出
全部空闲，或完成已经超时	三灯低亮

只要还有等待或工作，已完成的绿灯就不参与组合。同一段 Codex 会话可能同时出现在 Hook、旧状态文件和 rollout 里，聚合前会按软件和会话去重，Hook 优先，所以审批时的兜底记录不会再错误点亮黄灯。

某个软件退出时，只清掉它自己的活动。连续 30 分钟没有新事件，活动会回到空闲。

下载和安装

安装包在 GitHub Releases。

平台	说明
macOS 12+	双击 `.pkg`，装到「应用程序」，并配置 Hooks 和开机自启。未签名时，按住 Control 点按安装包，选择「打开」
Windows 10/11 x64 / ARM64	双击对应架构的 `setup.exe`。以当前用户安装到 `%LOCALAPPDATA%\HarborLight`，不需要管理员。SmartScreen 拦截时，选「更多信息 → 仍要运行」

Windows 便携包解压后要先执行一次 HarborLight.exe install，才会写入 Hooks 和登录自启动。

从源码安装需要 Rust。macOS 还要 Xcode Command Line Tools，在仓库里执行 make install。Windows 还要带「使用 C++ 的桌面开发」的 MSVC Build Tools，编译后执行 harbor-light.exe install。

Hooks

一键安装会合并 Codex 和 Cursor 的用户级 Hooks，不会覆盖已有条目。手动配置时，命令必须写绝对路径。

软件	会点亮的状态
Codex	开始会话、提交提示、工具调用是黄灯；请求权限是红灯；停止或会话结束是绿灯
Cursor	提交提示是黄灯；明确要求审批，或执行出错，是红灯；正常结束是绿灯

Cursor 目前没有单独的审批事件。普通命令不会被当成「等待确认」，避免安装依赖这类正在执行的操作误亮红灯。用户级 Hooks 只看本地 Agent，Cloud Agent 这一版不会自动配置。

卸载

macOS 在仓库里执行 make uninstall。Windows 可以在「设置 → 应用」里卸载，或执行：

& "$env:LOCALAPPDATA\HarborLight\HarborLight.exe" uninstall

卸载会停掉程序、去掉开机自启，并只删掉 Hooks 里本工具写入的条目。你自己的其他 Hooks 会留下。