Codex Usage Widget

English | 简体中文

See the Codex limits available to your account, including 5-hour and weekly windows, without opening a browser. Codex Usage Widget runs locally on Windows and reads usage through the official Codex CLI app server.

This is an independent utility and is not an official OpenAI application.

Quick start

The widget requires Windows 10 version 1809 or newer, the Codex CLI on PATH, and a completed local sign-in.

1. Download the latest Windows x64 portable release.
2. Start CodexUsageWidget.exe after extraction or directly from the ZIP.
3. If usage does not appear, confirm that codex --version works in PowerShell and run codex login.

The portable release includes the .NET runtime. The executable is not currently code-signed, so Windows may show an unknown-publisher warning. Each GitHub release includes a SHA-256 checksum for verification.

When Windows starts the executable from a temporary ZIP location, the widget copies that version to %LOCALAPPDATA%\CodexUsageWidget\app\<version> and relaunches it. An executable started from an extracted folder continues to run there. Only one widget instance runs at a time.

If Codex is installed outside PATH, set CODEX_USAGE_WIDGET_CODEX_PATH to the full path of codex.cmd or codex.exe.

What it shows

• Remaining percentage and reset time for every general Codex usage window
• A selectable displayed limit shared by the widget headline, taskbar label, and tray icon
• Compact and detailed desktop-widget layouts selected from Settings or the quick chevron, including credits, spend controls, earned-reset expiration and redemption, token activity, and model-specific limits when Codex returns them
• System, light, and dark themes with five preset accent colors selected from Settings
• Automatic Windows-language selection with English fallback, plus English and Simplified Chinese overrides in Settings
• Windows regional, 24-hour, and 12-hour time formats selected from Settings
• A movable, always-on-top desktop widget and a compact label beside the notification area
• Live task activity dots based on official local Codex lifecycle hooks
• Automatic refresh every two minutes plus live rate-limit notifications
• Fullscreen-aware taskbar behavior, per-monitor DPI support, and optional start with Windows
• Local logs for diagnostics, with no telemetry or remote backend

Display modes and limit selection

Desktop widget. Shows the selected limit as the headline and keeps every general limit visible below it. Compact mode focuses on limits; Details adds account and token activity.

Taskbar label. Shows the same selected percentage beside the Windows notification area. The tray icon and its tooltip follow that selection too.

Choose 5h limit, Weekly limit, or Most constrained in Settings under Usage. The 5-hour window is the default. Available windows depend on the Codex account, so the widget falls back to an available window when Codex does not return the selected one.

Token activity is informational. Token counts do not map directly to the remaining subscription percentage.