The main Codex limit stays clear
Usage Overlay deliberately selects the main Codex limit and keeps Spark or other model-specific buckets out of the interface.
Open-source Windows companion
Your Codex limit,without leaving your work.
Usage Overlay keeps the main Codex usage limit beside the desktop app. It shows primary and secondary main-limit details when returned, hides model-specific rows, and leaves credentials and conversations outside its boundary.
Version 0.3.1 · Windows 10/11 x64 · Installer + portable ZIP · MIT licence · Unsigned release
- Windows companion
- Windows 10 and 11 on x64
- Main limit only
- Model-specific rows stay hidden
- Private by scope
- No credentials or conversations
- Local and inspectable
- Redacted logs, optional reporting
Focused on the main limit
The useful signal stays visible. Everything else stays out of the way.
The rail keeps the main Codex limit in view. The detail card adds returned primary and secondary windows, reset timing, and connection status.
Both main-limit windows when returned
The detail card shows primary and secondary windows as separate labelled rows when App Server provides both.
Account changes clear stale usage
Signing out or switching Codex accounts clears the previous reading and refreshes usage for the active account.
Optional threshold notifications
Windows alerts can fire once when a returned limit crosses the configured amber or red threshold. They are off by default.
Updates stay manual
Check for updates makes one user-triggered request to the public GitHub release endpoint and never installs anything automatically.
Safe maintenance and system dialogs
Disconnect releases only the App Server child process started by Usage Overlay. The rail also stays hidden on Codex-owned file picker, Open, and Save dialogs.
Platform support
Windows today. Codex usage in the current release.
The published v0.3.1 build is a Windows x64 companion for Codex. We are evaluating Cursor support separately; it is not available in this download.
- Windows 10 and 11
- The public release supports 64-bit Windows, as an installer or portable ZIP.
- Codex Desktop and CLI
- Usage is read from the signed-in Codex account through Codex App Server.
- Cursor
- Cursor support is being evaluated and is not included in the current public release.
A narrow connection
Built beside Codex, not inside it.
Codex CLI keeps account ownership and network access. Usage Overlay requests rate-limit metadata through the documented App Server surface and renders it in a separate WPF process.
After you sign into another account in Codex, the overlay reloads usage automatically, normally within about seven seconds plus the request time when the login is saved to disk. Credential-manager changes can take about a minute. An expired login still needs you to sign in again; fresh usage requires a working connection.
Read App Server documentation- 01
Start App Server
Usage Overlay launches codex app-server --stdio as a child process.
- 02
Detect account changes
It checks saved login-file timestamps and size every two seconds. A change clears the previous account’s usage and reconnects the overlay automatically, without reading credential contents.
- 03
Read the main limit
It requests account/rateLimits/read, exposes the main bucket’s primary and secondary windows, and hides model-specific buckets.
- 04
Stay current and recover
Routine polls no longer force token refreshes. Stalled requests reconnect after 30 seconds, and late replies cannot restore usage from a previous account.
Privacy by scope
It asks for usage metadata, not your work.
The product boundary is narrow in code and visible in the public repository. Account ownership stays with Codex CLI; Usage Overlay keeps only local settings and redacted diagnostics.
No credential or conversation access
Codex owns authentication and account-data network access. Usage Overlay checks login-file metadata to detect changes, but never reads or writes credential contents. It does not request prompts, responses, history, repository files, API keys, passwords, or cookies.
Local settings and redacted logs
Preferences and diagnostic logs remain under the current Windows user profile. Sensitive-looking values are redacted before diagnostic messages are written.
Reporting is your choice
Installation reporting is optional and off by default: a random installation ID and app version are sent to Haroone at most once per UTC day while running. No account, conversation, quota or log data is sent. Daily activity expires after 90 days; summaries expire after 90 inactive days. Disable reporting in Settings to stop future reports. There is no analytics SDK or advertising.
Native settings
Control the behavior without editing a file.
General, Visibility, Position, Appearance, and Connection & diagnostics controls stay together. Save and Cancel are explicit, theme choices preview safely, and validation keeps impossible thresholds or paths from being written.
- Only in Codex or across Windows
- Hide while Codex is fullscreen
- Custom hover keeps the full rail fixed and aligned
- Multi-monitor tracking
- Pause for 15 minutes
- Windows startup and tray recovery
- Optional amber and red alerts
- Threshold and refresh validation
Installation and trust
Download from one public source. Verify before you run it.
Download app opens the public 0.3.1 installer. A portable ZIP and SHA256SUMS file are available in the same GitHub Release for users who prefer a manual install or want to verify the package before launch.
- 01
Download 0.3.1
The installer, portable ZIP, manifest, and checksum file are published on GitHub.
- 02
Choose setup or ZIP
The installer adds a normal Installed apps entry and uninstaller.
- 03
Check the hash
Compare the download with the published SHA256SUMS value.
Release status
Version 0.3.1 fixes automatic detection of Codex logout, login, and account switching. It passed a zero-warning Release build, all 18 specifications, simulated account-switch regression checks, live usage and reconnect checks, and package validation.
The published SHA-256 values match GitHub’s asset digests for both downloads. The installer is unsigned, so Windows SmartScreen may warn on first launch.
Go deeper
See the decisions behind the product.
The case study covers the product tradeoffs, App Server connection, privacy boundary, testing, and open-source preparation.