# codex-status-float

**Repository Path**: solalab/codex-status-float

## Basic Information

- **Project Name**: codex-status-float
- **Description**: 一个轻巧的桌面浮窗，Codex 任务状态、运行数量、待确认请求和已完成任务，一眼就能看到。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-04
- **Last Updated**: 2026-10-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Codex 状态浮窗（macOS）

一个可拖动、置顶的小窗，用来查看本机 Codex 桌面版的任务状态。浮窗会出现在所有桌面空间，点击浮窗可打开任务菜单；拖动浮窗可调整位置。

## 状态与任务菜单

| 状态 | 浮窗显示 | 判定 |
| --- | --- | --- |
| 运行中 | 绿色“运行中 · 数量”，光晕和圆点缓慢呼吸 | 至少一个本地任务正在运行，且确认检测已授权 |
| 空闲 | 冷灰蓝“空闲 · 5小时剩余百分比” | Codex 正在运行，但没有检测到运行中的任务；额度暂不可用时只显示“空闲” |
| 待确认 | 琥珀色“待确认” | Codex 窗口或当前前台应用窗口中出现确认或授权按钮 |
| 待回复 | 琥珀色“待回复” | Codex 窗口或当前前台应用窗口中出现带“跳过”按钮的提问弹窗 |
| 需授权 | 珊瑚色“需授权” | 检测到运行中的任务，但辅助功能授权未生效，无法判断是否待确认 |
| 未连接 | 灰色“未连接” | Codex 桌面版未运行，或本地状态监控暂时不可用 |

“运行中”状态会显示任务数。如果 Codex 中有带未读小点的已完成任务，任何状态旁都会附加 `✓` 和待查看数量，例如“运行中 · 3  ✓1”。系统启用“减少动态效果”时，运行中的呼吸动画会停止。

菜单先列出“已完成”的待查看任务及完成时间，再列出待回复、待确认和进行中的任务。点击任务标题会在 Codex 中打开该任务；成功打开已完成任务后，浮窗会从待查看列表中移除这一条。打开菜单本身不会清除列表，其他待查看任务会保留。列表也会随 Codex 的未读小点状态更新。菜单底部提供确认检测设置和退出入口。

运行任务只统计本机、未归档的主任务：其最新一轮仍在运行，且开始时间在最近 24 小时内。子代理任务不会单独计数。状态监控默认每 2 秒读取一次本地数据；空闲时通过 Codex app-server 的 `account/rateLimits/read` 每分钟读取一次 5 小时窗口用量；浮窗每秒检查 Codex 进程和确认按钮。

## 运行环境

- macOS 13 或更新版本，以及本机运行的 Codex 桌面版。
- 可运行的 `/usr/bin/python3`。应用启动时会通过这个固定路径读取 Codex 本地任务状态；只使用 Python 标准库，无需安装 pip 包。
- Codex 在 `~/.codex` 下生成的本地状态文件。没有这些文件时，浮窗会显示“未连接”。
- 识别“待确认”和“待回复”需要给 Codex Status Float 辅助功能权限；未授权时仍能读取运行任务，有任务运行时浮窗会显示“需授权”。

已构建的 App 不需要 Xcode 或 Swift 编译器。可用 `/usr/bin/python3 --version` 检查运行时依赖。

## 从源码构建与启动

源码仓库：[Gitee · codex-status-float](https://gitee.com/solalab/codex-status-float)。可用提供的 Git 地址获取源码：

```sh
git clone https://gitee.com/solalab/codex-status-float.git
cd codex-status-float
```

从源码构建另需 Xcode 命令行工具，提供 `swiftc` 和 `swift`；不需要完整 Xcode。可用 `swiftc --version` 检查。进入项目根目录后运行：

```sh
./build.sh
open 'dist/Codex Status Float.app'
```

应用没有 Dock 图标。首次启动时，macOS 可能要求在“系统设置 → 隐私与安全性 → 辅助功能”中允许 Codex Status Float 读取 Codex 窗口的按钮。此权限用于识别“待确认”和“待回复”；未授权时，运行中的任务会显示“需授权”。

### 签名与分发

构建脚本优先使用 SHA-1 为 `28A2B830F08095E51170E76DD1C1D32176B8F537` 的开发者证书；本机没有该证书时自动使用临时签名，并在构建完成后显示实际签名。可用 `security find-identity -v -p codesigning` 查看本机证书。指定其他证书时，传入其完整名称或 SHA-1：

```sh
CODE_SIGN_IDENTITY='Apple Development: 你的姓名 (TEAMID)' ./build.sh
```

也可明确使用临时签名：`CODE_SIGN_IDENTITY=- ./build.sh`。更新临时签名的应用后，辅助功能授权可能失效，即使系统设置中仍显示已开启。此时将 Codex Status Float 的辅助功能开关关闭再开启。

准备在 Mac App Store 之外分发时，使用 `Developer ID Application` 证书并启用分发签名。脚本会启用 Hardened Runtime 和安全时间戳；分发前仍需另行公证应用。

```sh
CODE_SIGN_IDENTITY='Developer ID Application: 你的姓名 (TEAMID)' CODE_SIGN_DISTRIBUTION=1 ./build.sh
```

## 数据来源与限制

状态监控只读访问 `~/.codex/thread_history_1.sqlite`、`~/.codex/state_5.sqlite` 和 `~/.codex/.codex-global-state.json`，读取任务 ID、标题、运行状态、完成时间及未读小点状态。空闲时通过 Codex 自带 app-server 的 `account/rateLimits/read` 接口读取当前账号用量，只显示 300 分钟窗口的剩余百分比；登录状态或该窗口不可用时，浮窗仍显示“空闲”。它不读取对话内容，也不会修改 Codex 任务。辅助功能权限用于检查 Codex 窗口和当前前台应用窗口中的按钮文字。

“待确认”和“待回复”会检查 Codex 窗口和当前前台应用窗口中的确认按钮或提问弹窗“跳过”按钮，以覆盖由浏览器进程承载的 Browser use 授权弹窗。若多个任务同时运行，而窗口标题无法唯一对应任务，菜单会显示“当前窗口有待确认请求 · 打开 Codex”或“当前窗口有待回复问题 · 打开 Codex”；后台任务中未显示的请求可能仍显示为“运行中”。Codex 若改变本地数据结构、任务链接格式或按钮文字，监控代码可能需要更新。

如果运行中的任务显示“需授权”，点击浮窗菜单中的“确认检测：需重新授权…”以打开系统设置，再将 Codex Status Float 的辅助功能开关关闭并重新开启。如果显示“未连接”，先确认 Codex 桌面版已经运行；也可使用下方的单次检测命令检查本地状态监控是否返回 `OFFLINE` 及错误信息。

## 开发与验证

`Scripts/codex_status.py` 读取本地任务数据并输出 JSON；`Sources/main.swift` 绘制浮窗、构建菜单并通过辅助功能识别确认按钮。`build.sh` 编译应用、生成图标并签名。运行单元测试和单次状态检测：

```sh
/usr/bin/python3 -m unittest discover -s Tests
/usr/bin/python3 Scripts/codex_status.py --once
```

单次检测会打印本机任务的 ID 和标题。需要用其他目录中的测试数据时，可传入 `--db-dir /path/to/codex-data`；持续检测可使用 `--interval` 调整轮询间隔（秒）。

## 宣传页与图标

项目根目录的 [index.html](index.html) 是独立的响应式宣传页，可直接在浏览器中打开；打印时会切换为横版海报布局。应用图标位于 [Assets/AppIcon.png](Assets/AppIcon.png)，绘制源文件是 [Scripts/generate_icon.swift](Scripts/generate_icon.swift)。`build.sh` 会生成各尺寸的 macOS 图标并打包进应用。