Codex Beacon 是独立社区项目，与 OpenAI 无隶属、合作或官方背书关系。Codex、OpenAI 及相关商标归其各自权利人所有。
前往 GitHub Releases 下载 Codex-Beacon_0.6.0_x64-setup.exe，运行安装程序即可。
首次启动后需要在 Codex 的“设置 → Hooks”或 CLI /hooks 中审核并信任 Codex Beacon Hook。所有任务状态都保存在本机。
Codex Beacon 只服务一个场景：在 Windows 桌面顶部持续呈现真实的 Codex 任务状态。
它通过 Codex Hook 在本机接收任务生命周期事件，并只读解析对应的本地 Codex rollout 来补充当前活动；不使用进程或 CPU 占用猜测状态，也不会把任务内容上传到外部服务。
- 状态先于装饰：任务状态点固定在标题前，项目名与耗时处于同一信息行；正式产品图标不重复承担状态提示。
- 一套语义颜色：运行使用青蓝、等待使用琥珀、完成使用绿色、失败使用红色，状态点、耗时和提示文字保持一致。
- 折叠也能读懂：折叠态保留任务、真实项目名、耗时和当前状态；展开态再提供最近任务、实时活动与回到对话。
- 克制的科技感：灯光只用于状态反馈，文字不加辉光；动效支持
prefers-reduced-motion。
完整说明见 DESIGN.md。
| 功能 | 说明 |
|---|---|
| 折叠态任务条 | 显示任务标题、项目、状态和耗时。 |
| 展开态会话面板 | 显示真实提示词、工作目录、模型、会话标识和最后回复。 |
| 实时活动 | 从本地 Codex rollout 显示最近动作、计划步骤以及待批准/待回复状态，不伪造总体完成百分比。 |
| 回到对话 | 使用任务 session_id 精确打开对应的 Codex Desktop 对话。 |
| 审批提醒 | 检测需要批准的操作并切换为琥珀色提醒，点击“前往批准”回到 Codex 完成审核。 |
| 最近任务 | 每个 session_id 只显示一条最新状态，最多保留 6 个真实用户对话。 |
| 状态自动纠错 | 对照本地 rollout 的终止事件与活动时间，过滤内部任务，并在 Hook 漏报或 Codex 异常退出后纠正失联状态。 |
| Windows 通知 | 仅在等待批准/回复、任务完成或任务失败时通知；点击通知直接打开对应 Codex 对话。 |
| 新版本检查 | 启动后检查 GitHub Release；发现新版本时在设置中提供下载入口，不执行自动更新。 |
| 状态动画 | 运行、完成、失败和长时间失联采用不同的克制反馈。 |
| 本地 Hook 安装 | 一键安装或修复 Codex Hook，并保留用户现有的非 Codex Beacon Hook。 |
| Windows 集成 | 始终置顶、可拖动与位置记忆、背景透明度调节、系统托盘、开机启动、单实例和透明点击穿透。 |
- 启动 Codex Beacon。
- 展开灵动岛，点击“连接 Codex”；也可以在设置中执行“安装/重装 Codex Hook”。
- 完全退出并重新打开 Codex，在“设置 → Hooks”中审核并信任 Codex Beacon Hook。CLI 中也可使用
/hooks。 - 在 Codex 中发送一条新任务。首次真实事件到达后，灵动岛会从“等待审核”切换为“已验证”。
- 后续任务会自动显示标题、工作项目、耗时、当前活动、完成状态与最后回复摘要。
- 任务需要批准或回复时，点击“前往批准”或“回到对话”即可打开对应的 Codex Desktop 对话。
命令行修复 Hook：
codex-beacon.exe --install-codex-hooks- Windows 10 或 Windows 11
- Node.js
- pnpm
- Rust 与 Cargo
- Microsoft Visual Studio Build Tools，包含 C++ 桌面开发工作负载
- Microsoft Edge WebView2 Runtime
- 已安装 Codex
pnpm install
pnpm tauri dev常用验证命令：
pnpm build
cargo test --manifest-path src-tauri/Cargo.toml
pnpm tauri build完整构建会生成 Windows 可执行文件与安装包：
src-tauri/target/release/codex-beacon.exe
src-tauri/target/release/bundle/nsis/Codex Beacon_0.6.0_x64-setup.exe
%APPDATA%\app.codexbeacon.desktop\codex-status.json
%APPDATA%\app.codexbeacon.desktop\codex-hook-verification.json
%APPDATA%\app.codexbeacon.desktop\codex-beacon-event.ps1
%USERPROFILE%\.codex\hooks.json
%USERPROFILE%\.codex\config.toml
codex-status.json最多保留 6 条 Hook 状态；界面会按session_id合并为一个对话，并过滤非用户 rollout。codex-hook-verification.json只在 Codex 实际执行 Hook 后生成，用于区分“文件已配置”和“连接已验证”。- 安装或重装 Hook 会清除旧验证标记，下一条真实 Codex 任务会重新完成验证。
codex-beacon-event.ps1只接收 Codex Hook 的标准输入并原子写入状态文件。- 运行中的任务只读访问
%USERPROFILE%\.codex\sessions下对应的 rollout；Codex Beacon 不修改会话记录。 - 安装器只替换 Codex Beacon 管理的 Hook，其他 Hook 保持不变。
- 首次启动或修复 Hook 时会把旧数据目录中的任务状态迁移到
app.codexbeacon.desktop，旧 Hook 信任不会沿用。 - 安装器会在
config.toml的[features]中显式启用hooks = true，并保留其他设置。 - 开机启动使用
HKCU\Software\Microsoft\Windows\CurrentVersion\Run。
.
├── src/
│ ├── App.tsx # 状态与界面组合入口
│ ├── codex/ # Codex 类型、展示转换和 Tauri API
│ ├── desktop/ # Windows 桌面 API
│ ├── components/ # 任务、空状态和设置组件
│ ├── styles/ # 按界面区域拆分的视觉样式
│ ├── App.css # 样式导入入口
│ └── main.tsx
├── scripts/
│ └── codex-beacon-event.ps1 # Codex 生命周期事件写入
├── src-tauri/
│ ├── src/codex.rs # Codex 模块入口与数据模型
│ ├── src/codex/ # 状态、rollout、Hook 与存储模块
│ ├── src/desktop.rs # Windows 窗口、托盘与开机启动
│ ├── src/lib.rs # Tauri 组合入口
│ ├── src/main.rs
│ └── tauri.conf.json
└── package.json
- 当前只支持 Windows 和 Codex。
- 当前通过稳定的
UserPromptSubmit与StopHook 获取任务开始和完成事件，并从本地 rollout 补充最近动作与计划步骤；计划计数不等于总体完成百分比。 - Codex Desktop 的审批通道没有向第三方窗口开放。Codex Beacon 只检测待批准状态并精确跳回对应对话，最终批准仍由 Codex 完成。
- “回到对话”依赖 Codex Desktop 当前提供的
codex://threads/{threadId}协议。 - Codex 异常退出或 Hook 漏报时，Codex Beacon 会优先读取 rollout 的终止事件；仍无终止事件且 10 分钟没有活动的任务会标记为“连接中断”。
- Windows 通知依赖系统通知权限；Codex Beacon 不在通知正文中显示任务标题。
- 新版本检查只读取 GitHub 最新 Release 标签，下载与安装仍由用户确认完成。
本项目使用 MIT License。