一个轻量、原生的 macOS 悬浮球，用来自动显示 Codex 当前任务状态和本周额度。
Native macOS floating status widget for Codex. Local-only, open source, and dependency-free.
- 默认显示一个 56 × 56 的小悬浮球，状态灯固定在中央。
- 鼠标停留 0.4 秒后展开，浮窗会依据屏幕空间自动选择方向。
- 绿灯：Codex 有任务，正在工作。
- 黄色状态：任务已经完成，等待查看；若仍有其他任务运行，中心保持绿灯并由黄色外圈提醒。
- 红灯：当前没有进行中的任务，也没有待查看的完成提醒。
- 灰灯：暂时无法读取 Codex 数据，避免把读取失败误报为空闲。
- 新任务完成时，悬浮球边框会在 1.8 秒内高亮三次，并保持低亮提醒，直到切回 Codex 或手动标记为已查看。
- 本周额度低于 50% 显示暗黄色，低于 30% 显示红色。
- 支持拖动定位、单击展开、跨桌面显示、外接屏热插拔和位置恢复。
- 展开和收起使用可打断的图层遮罩动画，快速移入、移出时会从当前位置自然反向。
- 数据每 1.5 秒在本机同步一次。
右键悬浮球即可调整：
- 尺寸：紧凑、标准、大号、特大；
- 主题：跟随系统、浅色、深色；
- 语气：简洁、温和、活泼，每种状态会轮换几句同义表达；
- 悬停响应：0.2、0.4、0.8 秒；
- 保持展开、重置位置、立即刷新和标记任务已查看。
应用会遵循 macOS 的“减少动态效果”“减少透明度”“增强对比度”和“不以颜色区分”辅助功能设置。开启“不以颜色区分”后，工作中、待查看和空闲会分别使用实心圆、圆环和短横。
应用不联网，不收集遥测，不读取 Codex 认证信息。
它仅以只读模式访问：
$CODEX_SQLITE_HOME/state_*.sqlite中的活跃任务索引；$CODEX_HOME/sessions/下数据库明确引用的.jsonl任务事件。
默认的 CODEX_HOME 是 ~/.codex，CODEX_SQLITE_HOME 默认跟随它。数据库会启用 SQLite query_only，任务文件也会经过路径、后缀、普通文件和真实路径校验。
从 Releases 下载 universal2 ZIP，解压后将 Codex 状态浮窗.app 放入“应用程序”。同一个安装包支持 Apple 芯片和 Intel Mac。
首次打开若被 macOS 拦截，可在 Finder 中右键应用并选择“打开”。Release 使用 ad-hoc 签名，没有 Apple Developer ID 公证。
要求：
- macOS 13 或更高版本
- Apple Command Line Tools
make test
make package应用生成在 build/，可分发 ZIP 生成在 dist/。安装当前构建：
make install默认生成 universal2 安装包。也可通过 TARGET_ARCH=arm64 或 TARGET_ARCH=x86_64 生成单架构版本。
生成界面预览：
zsh scripts/render-previews.shSources/App/ 悬浮窗、设置、布局和文案
Sources/Monitoring/ Codex 数据读取与事件解析
Tests/ 解析器、监控器、设置与渲染测试
Resources/Info.plist macOS 应用元数据
scripts/ 构建、测试和安装脚本
docs/images/ 由真实 AppKit 视图生成的预览
监控器读取 Codex 任务事件：
task_started→ 绿灯task_complete/turn_aborted→ 产生未查看完成提醒；无活跃任务时变为黄灯，有活跃任务时保持绿灯并显示黄色外圈- 存在未查看完成项时，单击悬浮球 → 展开并显示“有任务已完成”，不会提前清除提醒
- 用户切回 Codex 或选择“标记为已查看” → 清除完成提醒
长任务会通过渐进式尾部扫描识别，后续更新使用增量解析和文件身份缓存。实现会处理 UTF-8 分片、半写入事件、超过 32 MiB 的单次增长、日志轮转、未来数据库版本和暂时读取失败。为避免异常中断永久显示绿灯，超过 12 小时且没有新事件的任务会被视为过期。本周额度到达重置时间后会自动失效。
Codex 的本地存储格式属于内部实现，未来版本可能变化。若状态失准，请附上 macOS 与 Codex 版本提交 Issue，避免上传任何真实任务内容。
请阅读 CONTRIBUTING.md 和 SECURITY.md。
0BSD：可以免费使用、复制、修改、分发，也可以用于商业项目。