An unofficial Windows widget that stays on top while Codex Desktop is running and shows the remaining weekly usage allowance.
- Appears while Codex Desktop is running and hides when Codex exits.
- Reads the weekly usage window from the local Codex app-server.
- Refreshes every 60 seconds; double-click to refresh immediately.
- Supports dragging, copying the current value, and toggling always-on-top.
- Starts a small background watcher at Windows sign-in so it can follow future Codex launches.
The widget does not store login tokens, account details, or usage history. See PRIVACY.md.
Important
This is an unofficial community project. It relies on an experimental local Codex app-server method (account/rateLimits/read) that may change without notice.
- Windows 10 or 11
- Codex Desktop installed and signed in
- .NET 8 Desktop Runtime
- .NET 8 SDK only when building from source
- Download and extract the Windows zip from Releases.
- Review the included PowerShell scripts.
- Run:
.\scripts\install.ps1The app is installed to %LOCALAPPDATA%\CodexWeeklyUsageIndicator and a per-user Startup shortcut is created.
To uninstall:
.\scripts\uninstall.ps1Release binaries are currently unsigned, so Windows may display a warning. SHA-256 checksums are included with each release.
.\scripts\build.ps1The executable is written to dist\WeeklyUsageIndicator.exe. Release builds omit debug paths and symbols.
The WinForms process checks for the packaged Codex Desktop host. While Codex is active, it launches codex app-server --stdio, initializes the local JSONL protocol, and reads account/rateLimits/read. It selects the rate-limit window closest to seven days and renders the remaining percentage.
The app-server child process is stopped whenever Codex is no longer running.
src/— WinForms applicationscripts/— build, install, and uninstall helpers.github/workflows/— clean Windows builds and tagged releasesAGENTS.md— guidance for coding agents