Codex Quota Widget | Codex 额度插件

Codex 额度插件是一款面向 macOS 和 Windows 的轻量桌面小组件，用来查看 Codex 剩余额度、重置倒计时、Token 消耗和正在运行的任务。它也是一个 Codex quota widget、Codex usage monitor 和 token usage tracker，读取本机已经登录的 Codex 数据，不内置、不上传任何账号凭据。

中文说明 | English

最新版本 / Latest Release

直接下载可用版本，不需要先 clone 源码：

• macOS v0.12.0（通用 ZIP，含安装/卸载入口）
• Windows v0.12.0（ZIP，含一键安装）
• 查看更新说明 / Release notes

macOS 解压后双击 Install.command；Windows 解压后双击 Install.cmd。首次使用前，请先在对应电脑上登录 Codex 或 ChatGPT。

中文说明

主要功能

• 真实额度数据：直接显示 Codex 服务端返回的当前额度与重置时间，不把额度窗口写死为“5 小时”，也不会用本地 Token 伪造小数精度。
• 动态额度水球（macOS）：额度充足时呈深紫色，随着额度消耗逐渐过渡到蓝色、浅蓝色，接近 0 时变成透明水色。
• 受力与能量动画（macOS）：拖动窗口时球体会按惯性和表面张力轻微形变并平稳恢复；粒子从球体随机向外释放。1/2/3/4 个并行任务对应四档粒子数量，模型与 reasoning 等级越高，粒子消散越快；所有活动会话的实际 Token 消耗速度会继续放大或减弱档位内的密度与速度。
• Token 与任务状态：显示本次任务 Token、累计 Token、额度重置倒计时、重置次数以及当前运行任务数。
• 菜单栏常驻（macOS）：使用经典 Codex 素描图标并显示整数百分比；左键打开额度窗口，右键可查看 Codex 任务与最近会话，并执行刷新或退出。
• 桌面行为（macOS）：启动 Codex 时自动运行；关闭小窗只会隐藏，不会退出后台；切换到其他桌面或全屏空间时，小窗不会跟随过去。
• 稳定刷新：请求失败时自动重试并保留最后一次有效数据，避免网络波动被错误显示为 100%。
• Windows 支持：提供托盘图标、额度小窗、刷新/退出菜单、开机启动以及一键安装和卸载。
• 轻量运行：动画采用固定粒子池并在窗口隐藏时暂停，减少 CPU 和内存占用。

macOS 安装

要求：macOS 13 或更高版本、已登录 Codex/ChatGPT、已安装 Xcode Command Line Tools。

推荐直接下载上方的 macOS Release。解压后双击 Install.command，它会把应用安装到 ~/Applications 并注册自动启动；卸载时双击同目录的 Uninstall.command。

git clone https://github.com/wangxinyue385-tech/codex-quota-widget.git
cd codex-quota-widget
bash macOS/install-macos.sh

安装脚本会编译应用到 ~/Applications/CodexQuotaWidget.app，安装后台启动项，并立即打开小组件。以后启动 Codex 时，小组件会自动启动。

卸载：

bash macOS/uninstall-macos.sh

Windows 安装

要求：Windows 10/11、已登录 Codex/ChatGPT、Windows PowerShell 5.1 或更高版本。

推荐直接下载上方的 Windows Release，解压后双击 Install.cmd。

1. 下载并解压 windows/CodexQuotaWidget-Windows.zip。
2. 打开 CodexQuotaWidget-Windows 文件夹。
3. 双击 Install.cmd。

安装后会创建桌面快捷方式、开始菜单快捷方式和开机启动项。托盘图标左键打开额度详情，右键提供刷新和退出。卸载时运行开始菜单中的“卸载 Codex Quota Widget”或 Uninstall.cmd。

数据与隐私

本项目不是 OpenAI 官方客户端，也不会绕过登录或额度限制。额度来自当前登录的 Codex 客户端与服务端返回结果，Token 统计来自本机 Codex 会话文件：

• macOS：~/.codex/auth.json、~/.codex/sessions/ 和 Codex 本地会话数据库。
• Windows：%USERPROFILE%\.codex\auth.json 和 %USERPROFILE%\.codex\sessions\*.jsonl。

源码只读取这些本地数据。仓库不包含访问令牌、刷新令牌、会话记录或个人路径。请勿把自己的 auth.json、access-token.txt 或 .codex 目录发送给任何人。

English

Overview

Codex Quota Widget is a lightweight Codex quota and usage monitor for macOS and Windows. It shows the official remaining quota, reset countdown, token usage, reset credits, and active task count by using the Codex session already signed in on the local computer.

Features

• Official quota data: displays the quota and reset window returned by Codex without hard-coding a five-hour limit or inventing decimal precision from local token counts.
• Animated quota orb on macOS: the fluid orb starts deep purple at high quota, then transitions through blue and light blue toward clear water as quota is consumed.
• Responsive motion and energy release on macOS: dragging applies restrained inertia and surface-tension deformation. Particles leave the orb in randomized directions. One, two, three, and four active tasks map to four particle-count tiers; stronger models and reasoning levels make particles dissipate faster, while the combined real token burn rate modulates density and speed within each tier.
• Live activity metrics: shows current-task tokens, cumulative tokens, reset countdown, reset credits, and active Codex tasks.
• macOS menu bar integration: uses the classic sketch-style Codex icon with an integer percentage. Left-click opens the widget; right-click exposes Codex tasks, recent sessions, refresh, and quit actions.
• Desktop-friendly behavior on macOS: launches with Codex, hides instead of quitting when the widget is closed, and stays out of unrelated desktops and full-screen Spaces.
• Resilient updates: retries transient failures and keeps the last valid reading instead of incorrectly jumping to 100%.
• Windows support: includes a system-tray icon, quota window, refresh/quit menu, startup registration, and one-click install/uninstall scripts.
• Low overhead: uses a bounded particle pool and pauses animation while the widget is hidden to reduce CPU and memory use.

Install on macOS

Requirements: macOS 13 or later, a signed-in Codex/ChatGPT session, and Xcode Command Line Tools.

For the easiest install, download the macOS Release above, unzip it, and double-click Install.command. It installs the app in ~/Applications and registers automatic startup. Use Uninstall.command in the same folder to remove it.

git clone https://github.com/wangxinyue385-tech/codex-quota-widget.git
cd codex-quota-widget
bash macOS/install-macos.sh

The installer builds the app at ~/Applications/CodexQuotaWidget.app, installs its background launch agent, and opens it immediately. The widget will start automatically when Codex starts.

Uninstall:

bash macOS/uninstall-macos.sh

Install on Windows

Requirements: Windows 10/11, a signed-in Codex/ChatGPT session, and Windows PowerShell 5.1 or later.

For the easiest install, download the Windows Release above, extract it, and double-click Install.cmd.

1. Download and extract windows/CodexQuotaWidget-Windows.zip.
2. Open the extracted CodexQuotaWidget-Windows folder.
3. Double-click Install.cmd.

The installer adds desktop and Start menu shortcuts plus a startup entry. Left-click the tray icon to open quota details; right-click to refresh or quit. To remove it, use “Uninstall Codex Quota Widget” from the Start menu or run Uninstall.cmd.

Data and privacy

This is an unofficial community project. It does not bypass authentication or quota limits. Quota data comes from the currently signed-in Codex client and its service response; token totals come from local Codex session files. No credentials, access tokens, refresh tokens, session logs, or personal paths are included in this repository.

Project Structure

macOS/
  Sources/                          Swift and Objective-C sources
  assets/                           Menu bar icon
  build-macos.sh                    Build script
  install-macos.sh                  Build, install, and enable startup
  uninstall-macos.sh                Uninstaller
windows/
  CodexQuotaWidget-Windows/         Windows source and install scripts
  CodexQuotaWidget-Windows.zip      Ready-to-share Windows package
docs/
  quota-dashboard.png               Latest widget screenshot

Known Limitations

• The Codex quota response usually contains an integer percentage. The widget will only show decimals if the service provides them.
• Native glass appearance varies by macOS version and available window APIs; older systems use a compatible blur material.
• The Windows PowerShell/WinForms version provides the core monitoring workflow but does not reproduce every macOS visual effect.
• The quota endpoint is used internally by the Codex client and may change in a future client release.

Search Keywords / 搜索关键词

Codex 额度插件、Codex 额度监控、Codex 使用量、Codex Token 消耗、Codex 桌面小组件、Codex 菜单栏；Codex quota widget, Codex usage monitor, Codex token tracker, Codex desktop widget, Codex menu bar app, Codex system tray.

License

MIT License. See LICENSE.