在 macOS 菜单栏和桌面小组件中查看 Codex 剩余额度与最近 7 天用量。
English · 安装 · 常见问题 · MIT License
Quota for Codex 是独立第三方开源项目,不隶属于 OpenAI。
Native Runtime Integration · Actor-isolated RPC · Cross-Process State Synchronization
应用围绕 本地运行时接入 → 额度语义归一化 → 跨进程快照 → 原生系统呈现 组织工程边界。Swift Actor 管理 stdio 会话与请求生命周期,主应用将额度和用量投影为 App Group 原子快照,WidgetKit 消费该快照。
| 技术域 | 工程实现 |
|---|---|
| Async RPC Transport | 请求 ID 关联、CheckedContinuation、通知事件流、超时与进程退出清理 |
| Snapshot Projection | 整体额度桶选择、七日用量聚合、缺失日补零与部分失败回退 |
| Cross-Process State | 单写入方的 Codable JSON 原子快照与 App Group 共享容器 |
| Runtime Lifecycle | 轮询、事件驱动刷新、系统唤醒恢复与 stale 状态呈现 |
| Verification Harness | Fake-server 协议测试、映射/存储验证与独立 smoke executable |
- 小号 Widget:显示 5 小时额度、周额度及重置时间。
- 中号 Widget:在额度信息右侧显示最近 7 天 token 用量柱状图。
- 菜单栏应用:查看同步状态、立即刷新和打开设置。
- 自动刷新:额度约每 60 秒检查一次,趋势约每 15 分钟更新一次。
- 登录时启动:可在设置中开启或关闭。
- 自动寻找 Codex:支持 ChatGPT/Codex 桌面应用内置版本、Homebrew 和
PATH中的 CLI,也可手动选择。 - 本地优先:不读取或保存 Codex 登录凭证,不上传额度数据。
不同账号不一定同时提供 5 小时和周额度。缺失窗口会显示“暂无数据”。
- macOS 14 Sonoma 或更高版本。
- 已安装并登录 ChatGPT/Codex 桌面应用,或已登录 Codex CLI。
- 从源码安装时需要完整 Xcode 和 XcodeGen。
当前仓库暂未提供经过 Developer ID 公证的 DMG,因此首次安装需要从源码构建。
git clone https://github.com/yuanjuju/QuotaForCodex.git
cd QuotaForCodex- 从 Mac App Store 安装完整 Xcode。
- 打开 Xcode,在
Settings -> Accounts中登录 Apple ID。 - 安装 XcodeGen:
brew install xcodegen./scripts/install-local.sh脚本会自动生成工程、识别开发团队、完成签名,并安装到:
~/Applications/Quota for Codex.app
如果自动识别失败,可以显式传入 Team ID:
APPLE_TEAM_ID='YOUR_TEAM_ID' ./scripts/install-local.sh如果 Xcode 提示 Bundle Identifier 已被占用,先换成自己的反向域名标识,再重新安装:
./scripts/configure-identifiers.sh com.yourname
./scripts/install-local.sh此操作会修改本地工程的 Bundle ID 和 App Group。请使用只包含英文字母、数字和点的唯一前缀。
- 启动
Quota for Codex,菜单栏会出现仪表图标。 - 在桌面空白处右键,选择“编辑小组件”。
- 搜索
Quota for Codex。 - 选择小号或中号,然后拖到桌面。
- 如需持续更新,在应用设置中打开“登录时启动”。
WidgetKit 的最终刷新时间由 macOS 调度。菜单栏数据通常会更快更新,桌面小组件不能保证秒级刷新。
点击菜单栏图标可以:
- 查看 5 小时和周额度。
- 查看最后更新时间及当前连接状态。
- 点击“刷新”立即重新同步额度和趋势。
- 打开设置,测试连接或选择其他 Codex 可执行文件。
- 开启登录时启动。
额度颜色含义:
| 剩余额度 | 颜色 |
|---|---|
| 50%–100% | 绿色 |
| 20%–49% | 橙色 |
| 0%–19% | 红色 |
先确认 ChatGPT/Codex 桌面应用或 Codex CLI 已安装。也可以在设置中点击“选择可执行文件”,手动选择 codex。
打开 ChatGPT/Codex 或在终端登录 Codex CLI,确认能够正常使用后,再点击菜单栏中的“刷新”。
菜单栏应用会立即请求 WidgetKit 刷新,但 macOS 可能延迟更新时间线。请保持菜单栏应用运行,并开启“登录时启动”。
确认已在 Xcode 登录 Apple ID。如果 Bundle ID 与其他开发者冲突,请运行:
./scripts/configure-identifiers.sh com.yourname然后重新执行安装脚本。
Personal Team 的开发签名会定期过期。重新运行 ./scripts/install-local.sh 即可覆盖安装。
应用通过本机的 codex app-server --listen stdio:// 读取:
account/rateLimits/readaccount/usage/read
额度快照只写入本机 App Group 容器,供主应用和 Widget Extension 共享。项目不会读取 ~/.codex/auth.json,不会保存账号密钥,也没有自建云端服务。
生成 Xcode 工程并运行完整测试:
./scripts/bootstrap.sh只测试共享 Swift 包:
swift test使用当前登录账号运行只读连接探针:
swift run QuotaProbe运行不依赖真实账号的烟雾测试:
swift run QuotaSmokeproject.yml 是 Xcode 工程配置的来源。修改目标、签名或构建设置后,请运行:
xcodegen generate更多工程约定请参阅 agents.md,参与开发前请阅读 CONTRIBUTING.md。
本机 Codex 可执行文件
↓ stdio JSON-RPC
菜单栏主应用
↓ 原子 JSON 快照
App Group 容器
↙ ↘
菜单栏 WidgetKit
主应用负责 Codex 进程生命周期、轮询与错误处理;Widget Extension 只读取快照,不直接启动 Codex,也不接触登录凭证。
维护者可使用 scripts/release.sh 构建 Universal 2、Developer ID 签名并公证的 DMG。需要 Apple Developer Program、Developer ID Application 证书和 notarytool profile。具体环境变量参见脚本。
- WidgetKit 刷新受 macOS 调度限制。
- Codex app-server 协议未来可能变化。
- 当前只显示整体
codex额度,不显示模型专属额度桶。 - 仅支持 macOS,不包含 iPhone/iPad、云同步、通知和自动更新。
本项目使用 MIT License。