Codex Usage Bar

Codex limits, where you actually need them.

A lightweight native Windows overlay that places your remaining Codex usage and reset countdown directly inside the composer toolbar.

---

Why this exists

Codex exposes usage information in settings, but checking settings repeatedly interrupts the workflow. Codex Usage Bar keeps the information visible in the composer itself: remaining quota, a compact progress ring, and the time until reset.

The project is intentionally implemented as a tiny native Windows helper rather than an Electron application, browser extension, injected script, or modified Codex build.

Native feel Samples the Codex composer surface and renders directly over unused toolbar space so the readout blends into the current UI.

Minimal footprint One WinForms process. No Electron, Node.js, Python runtime, embedded browser, tray dashboard, or background console.

Private by design No analytics or telemetry. Authentication is read locally and used only to request your own usage data from ChatGPT.

Features

• Remaining Codex quota shown directly in the composer toolbar.
• Live countdown to the next usage reset.
• Compact progress ring with low-quota warning colors.
• Supports weekly-only accounts and multiple usage windows when exposed by the backend.
• Automatically follows the Codex/ChatGPT window.
• Automatically hides when Codex/ChatGPT is not the active application.
• Click-through and non-activating; it does not steal mouse or keyboard focus.
• Adapts to light and dark surfaces by sampling the composer background.
• Optional Windows startup shortcut.
• No installer required.
• Fully auditable single-file C# core.

Installation

Recommended: prebuilt release

1. Open the latest release.
2. Download CodexUsageBar-v1.0.0-windows.zip.
3. Extract the ZIP to a permanent folder.
4. Run CodexUsageBar.exe.
5. Focus Codex/ChatGPT. The usage readout should appear in the composer toolbar.

To launch it automatically with Windows, run:

scripts\Install-Startup.cmd

No administrator privileges are required for the normal install/startup workflow.

Build from source

Clone the repository and run:

Build.cmd

Build.cmd uses the .NET Framework C# compiler included with Windows and writes CodexUsageBar.exe to the repository root.

How it works

Codex Usage Bar does not patch, inject into, or modify the Codex application.

It runs as an independent borderless WinForms window with three responsibilities:

1. Detect Codex — the foreground root window is checked for the current ChatGPT.exe or Codex.exe host process.
2. Render the overlay — the helper follows the host window, samples the composer surface, and draws the usage readout in the toolbar gap.
3. Read usage — the existing local Codex authentication is used for a read-only HTTPS request to the ChatGPT usage backend. Reset countdowns are then calculated locally between refreshes.

For implementation details, see Architecture.

Privacy and security

Codex Usage Bar reads the existing Codex authentication file from:

%USERPROFILE%\.codex\auth.json

or from CODEX_HOME when that environment variable is set.

It does not modify that file, write tokens to disk, log tokens, send telemetry, or contact advertising/analytics services. The authentication token is sent only to the ChatGPT usage endpoint required to retrieve the account's usage data.

The relevant code is contained in src/CodexUsageBar.cs and can be audited directly.

See Security Policy for reporting guidance.

Performance model

The project is designed around a minimal runtime footprint:

Component	Behavior
UI	Native WinForms/GDI rendering
Foreground and position check	Every 250 ms
Usage network refresh	At most once every 60 seconds while Codex is active
Reset countdown	Calculated locally
Runtime dependencies	.NET Framework / Windows APIs
Embedded browser	None
Telemetry	None

Exact memory usage depends on Windows and the installed .NET Framework version; no fixed RAM figure is advertised without repeatable measurements.

Compatibility

Item	Status
Windows 11	Supported
Windows 10	Expected to work; reports welcome
Codex inside the ChatGPT Windows app	Supported
Standalone Codex.exe host	Detected when present
Light and dark composer surfaces	Supported
Non-default scaling / unusual layouts	Best effort
macOS / Linux	Not supported by this implementation

The overlay position is tuned for the current Codex Windows composer. If OpenAI changes the application layout, an update may be required.

The usage request relies on an undocumented ChatGPT backend endpoint and can also require maintenance if that response schema changes.

Troubleshooting

The usage bar does not appear

• Make sure CodexUsageBar.exe is running.
• Focus the Codex/ChatGPT window; the overlay intentionally hides for other applications.
• Confirm Codex is signed in and %USERPROFILE%\.codex\auth.json exists.
• Restart the helper after updating Codex if the app process changed.

The bar is positioned incorrectly

Open an issue with:

• Windows version;
• display resolution;
• Windows scaling percentage;
• Codex window size/maximized state;
• a cropped screenshot of the composer toolbar with private content removed.

Usage shows as unavailable

Codex may have changed its local authentication format or usage response schema. Do not post auth.json or access tokens. Open an issue containing only the visible error behavior and application versions.

For developers

The repository is intentionally small.

.
├── src/
│   └── CodexUsageBar.cs
├── scripts/
│   ├── Install-Startup.cmd
│   └── Uninstall-Startup.cmd
├── docs/
│   └── ARCHITECTURE.md
├── .github/workflows/
│   └── build.yml
├── Build.cmd
├── CHANGELOG.md
├── CONTRIBUTING.md
├── SECURITY.md
└── LICENSE

Before changing placement or rendering logic, test at multiple Windows scaling factors. Before changing usage parsing, avoid logging raw backend responses because they may contain account-related data.

See Contributing before opening a pull request.

Releases

Releases follow Semantic Versioning.

• Patch (1.0.1): bug fixes and compatibility patches.
• Minor (1.1.0): backward-compatible features.
• Major (2.0.0): substantial redesigns or breaking behavior changes.

Every release package is accompanied by a SHA-256 checksum generated by GitHub Actions.

Uninstall

Run:

scripts\Uninstall-Startup.cmd

Then delete the folder containing Codex Usage Bar. The application does not install services, drivers, browser extensions, or system components.

Disclaimer

Codex Usage Bar is an unofficial community project. It is not affiliated with, sponsored by, or endorsed by OpenAI. Codex, ChatGPT, and OpenAI are trademarks of their respective owner.

License

Released under the MIT License.