# CodexQuotaTray

**Repository Path**: niray/CodexQuotaTray

## Basic Information

- **Project Name**: CodexQuotaTray
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 2
- **Forks**: 1
- **Created**: 2026-10-12
- **Last Updated**: 2026-10-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Codex 周额度托盘

Windows 系统托盘显示 Codex 周额度，同时提供当前本地会话的 Git 分支悬浮窗。
1.5.0 起增加 C# 内嵌模式，在 Codex 输入框附近显示分支与周额度。仅页面组件使用内置 JavaScript/CSS，运行不需要 Node.js。

## 内嵌模式

1. 托盘右键 → “Codex 内嵌显示”，首次升级默认开启，独立悬浮窗默认隐藏（仍可手动显示）。
2. 保存任务，从 Codex 自己的托盘菜单完全退出。仅关闭主窗口可能仍驻留后台。
3. 在我们工具的托盘菜单选择“打开支持内嵌的 Codex…”，确认后按动态读取的 Store 应用标识启动。
4. 当前连接状态显示在该子菜单第一行。内嵌未连接不影响原有额度托盘。

- 仅使用 `127.0.0.1:39222`，不会自动结束 Codex、修改安装包、更新策略、代理或防火墙。调试端口可以被本机其他程序访问，不能视作鉴权接口，不要向外网转发。
- 内嵌依赖 Codex 页面内部属性，客户端改版可能失效。多窗口按活动会话 ID 读取实际 cwd；不能可靠区分的新建页或折叠侧栏多窗口状态显示等待，不猜测分支。
- 关闭“启用内嵌显示”后清理组件；要关闭调试端口，必须完全退出 Codex，再使用原图标打开。普通原图标启动不自动添加调试参数，本工具不会接管启动。
- 工具退出或通信中断后，页面组件约 10 秒自动清理；不将过期额度继续显示。15 分钟以上的额度、已到重置时间而尚未刷新、无效窗口均显示 —。
- 配置保存到 `%LOCALAPPDATA%\CodexQuotaTray\embedded.xml`，原有额度和悬浮窗设置保留。需要 .NET Framework 4.8；无 Node.js 或第三方自动更新依赖。
- 软件及 C# 通信已在独立 Chromium 测试页面验证；1.5.3 在本机运行中的 Codex 验证了新建页项目分支、移除 5h 和免重启组件升级。其他客户端版本仍需实机验收。
- 1.5.1 新增“检查启动环境（不重启）”：只读查询 Appx 状态和运行情况。启动按钮先拒绝非 Ok 的应用包、已有 Codex 进程和占用的端口，然后后台验证最多约 45 秒；验证进程身份、可见窗口、响应及真实 CDP 读取，连续两次成功才标记就绪。不阻塞托盘、不自动重试、不修复或重新注册应用包。
- 启动诊断写入 `CodexQuotaTray.log` 和 `embedded-launch-state.json`，仅含时间、阶段、版本、PID 和错误码，不记录账号或页面内容。`0x80073D00` 提示 Windows 正在维护/更新应用包。窗口正常但调试接口未就绪不会误报为 Codex 启动失败。
- 1.5.2 修正端口空闲误判：直接只读查询系统 TCP 监听列表，不再通过 500 毫秒连接超时判断端口占用。启动记录额外保存固定的原因标识（如 codex-running、debug-port-in-use），不记录异常正文。
- 1.5.3 修复预加载 Page 被误算为第二个会话窗口的问题：按实际输入框上下文统计窗口，保留真实多窗口的不猜测保护。内嵌仅显示分支和周额度，移除 5h 项；支持不重启 Codex 替换旧组件。
- 1.5.4 修复项目状态读取与 Windows 原子替换冲突：正式运行不再打开 `.codex-global-state.json`，通过已有本机 CDP 接口调用 Codex 的只读 `get-global-state` 桥接，仅请求 `selected-project` 和 `local-projects`。不读取草稿、persisted atoms、队列或账号字段，不执行状态写入。关闭内嵌显示后，独立分支功能仍可使用这条只读元数据通路；若接口未连接，新建页等待，不回退读文件。已有正式会话仍使用实际 cwd。

## 显示规则

- 托盘图标使用透明背景，数字放大到托盘安全边界，仅保留防裁切和描边空间。
- 数字本身着色：绿色表示剩余不少于 50%，橙色表示 20%～49%，红色表示低于 20%。
- 悬停显示完整周额度和重置时间。
- 右键菜单显示周额度、5 小时额度、数据状态、手动刷新和开机自启开关。

## 数据来源

1. 本机 `.codex` 当前会话记录；按额度事件的真实时间在所有会话中选最新值。
2. 使用 `%USERPROFILE%\.codex\auth.json` 查询的账户额度；仅当它与当前会话属于同一额度重置周期时采用。
3. Codex App Server 的 `account/rateLimits/read` 和额度更新通知。
4. 15 分钟内的最近成功额度缓存。

超过 15 分钟的本地记录或缓存不会继续显示成当前百分比。实时额度暂时取不到时，托盘显示灰色 `--`，避免旧数字误导。

主托盘只接受 `limit_id=codex` 的主 Codex 额度，GPT-5.3-Codex-Spark 等模型独立额度不会混入周额度显示。

程序只从 `%USERPROFILE%\.codex\auth.json` 在内存中读取访问令牌，用于发起只读额度请求；不会复制、缓存、显示或写入日志。如果该身份与当前 Codex 桌面会话的额度周期不一致，程序会拒绝其结果，避免跨账户或跨认证上下文串值。

账户额度请求允许最多等待 30 秒，以适应接口偶尔超过 10 秒才返回的情况。

## 安装

运行：

```text
CodexQuotaTray.exe --install
```

程序会安装到 `%LOCALAPPDATA%\CodexQuotaTray`、加入当前用户开机自启并启动托盘程序，不需要管理员权限。

## 分支悬浮窗

- 右键托盘数字 → “当前会话分支悬浮窗”，可显示/隐藏悬浮窗或打开外观设置。
- 默认显示并置顶；拖动文字或背景移动位置，拖动右下角改变宽高。
- 设置可调整文字颜色、背景颜色、宽高、字号和置顶。关闭悬浮窗只会隐藏它，托盘继续运行。
- 根据 Codex 桌面日志中当前窗口的页面/聚焦信息定位本地会话，只读查询会话数据库中的 cwd，再读取该目录的实时 Git 分支。
- 新建会话首页还没发送消息时，由本机只读桥接取得 `selected-project` 与 `local-projects`，显示已选本地项目主目录 `rootPaths[0]` 的分支；切换项目也会更新。不打开 Codex 全局状态文件，不使用可能过期的 `active-workspace-roots`。进入已有会话后始终按会话实际 cwd 读取。
- 正在创建会话或工作树时等待实际目录；侧栏仍显示客户端临时 ID、但唯一主窗口日志已有正式路由时，直接读取实际目录。新建页未选项目、主目录不存在、远程/云项目或接口暂时不可用时显示等待，不沿用旧分支。
- 已选项目状态是全局信息，不能可靠区分多个主窗口；有多个 Codex 主窗口时，新建首页暂不显示项目分支，进入实际会话后恢复。悬停文字可查看目录来源和完整路径。
- 支持 worktree；游离 HEAD 显示短提交号；非 Git 会话显示“无 Git 分支”，避免沿用上个会话的分支。
- 切换会话约每 0.5 秒检测，Git 分支约每 2 秒刷新。多窗口依据最近的聚焦证据选择窗口。
- 分支功能来自用户提供的 CodexBranchFloat-v3-Source.zip，集成其 BranchWindow、CodexFollower、GitProbe、Preferences 和 SettingsWindow 源码。
- 集成版共用原有额度托盘、退出入口和开机自启，不创建第二个托盘，也不登记独立悬浮窗自启。
- 设置保存在 %LOCALAPPDATA%\CodexQuotaTray\branch-float\settings.xml；第一次启动会迁移 %LOCALAPPDATA%\CodexBranchFloat 的外观与位置设置。
- 会话跟随依赖 Codex 内部桌面日志格式。如果格式变化，悬浮窗会显示等待状态，不改用最近运行的任务冒充当前会话。

## 构建与验证

使用 Windows 的 .NET Framework 编译器，目标 x64，WPF 与 WinForms 共同运行，无 NuGet 依赖：

```powershell
.\Build.ps1
.\tests\RunTests.ps1
```

集成测试创建独立 Git 仓库、worktree 和模拟 SQLite 数据库，验证设置、会话切换、无 Git 状态以及 WinForms 消息循环中的 WPF 悬浮窗。测试不修改真实会话数据库或自启登记。
默认测试数据放在 `%TEMP%\CodexQuotaTrayTests`，避免测试目录位于源码 Git 仓库内而使“非 Git”场景失效。Windows 并发测试在隔离文件上复现共享删除句柄仍阻止原子覆盖，并验证 16000 次内存元数据读取与 2000 次原子替换无共享失败；真实 Codex 全局状态文件不会被测试写入。
内嵌单元测试验证端点限制、原子设置、额度过期及工作树目录优先级；`tests/EmbeddedViewTests.cjs` 为可选的 Playwright 浏览器测试，覆盖 C# CDP 通信与 DOM 组件，不是运行依赖。

## 其他

- 双击托盘图标可立即刷新额度。
- 右键“打开系统健康检查”启动此前配置的系统健康检查工具。
- 右键托盘可关闭开机自启或退出。退出时同时关闭分支悬浮窗。
- 从 Codex 终端启动时使用源码根目录中的 Start-CodexQuotaTray.ps1，经 Windows 桌面启动已安装版本，以保持进程独立。
- 1.4.0 版本已移除全部更新策略控制、提权工作进程与自动回锁逻辑。以前的备份文件保留供查阅，新版不再读写更新策略。
- 日志和额度缓存位于 %LOCALAPPDATA%\CodexQuotaTray，日志不记录接口响应或凭证。

## 许可证

本项目采用 [MIT License](LICENSE)，版权署名为 `2026 niray`。允许使用、修改、分发和商用，复制源码或实质性部分时须保留版权声明与许可证全文。

集成的 `CodexBranchFloat-v3-Source.zip` 为项目所有者自己的 Codex 会话生成，项目所有者已确认将该部分一并按 MIT 发布。
本项目是非官方工具，与 OpenAI 无关联；MIT 许可证不授予第三方商标或 Codex 应用本身的权利。