WINDOWS · CODEX helper

Codex overlay guide: usage, context and updates

CodexUsageOverlay is a usage and update assistant for the Windows Codex desktop app. It follows the Codex window to display account quotas, reset times, tokens and task status, and offers local context information and desktop updates.

Author: Blues · Updated: 2026-10-14 · Based on the public README and installation guide

Information beside your window

The main usage bar shows plan, short-window and weekly quotas, reset times, available reset coupons, cumulative tokens and task status. Settings cover position, font, theme and refresh interval; the bar can open the Codex desktop MSIX update assistant.

The local context bar shows the matched session's context usage, cumulative tokens, cache hit rate and input/output breakdown. Native analytics covers products, models, clients, skills and plugins. Each area has its own data definitions.

This is an unofficial public helper, unaffiliated with and not endorsed by OpenAI. Preview numbers do not represent your account; rely on actual local Codex data.

Before first use

System: Windows 10/11 with built-in .NET Framework 4.x. This guide does not claim compatibility with macOS or Linux.
Client: An installed Codex desktop app. The tool prefers its bundled codex.exe and also supports the official local Codex CLI.
Login: An existing usable local Codex session. The account owner completes login or device authorization through the official flow.
Installer: Choose a public Release installer and its matching SHA-256 checksum for the same version/file. Keep settings and local data before updating.

If account data cannot be read, verify Codex login and CLI availability. Use CODEX_CLI_PATH to point to the actual CLI executable. Do not upload auth files, tokens or local sessions in public issue reports.

Install, focus the window and verify data

Choose the current release package. Open the latest public Release ↗ and check version, filename and matching checksums. Fixed links in older repository notes may reference old releases.
Verify before running. In PowerShell, use Get-FileHash -Algorithm SHA256 to hash the downloaded installer and compare character for character with the matching filename in the checksum file. Stop on a mismatch.
Complete current-user installation. Public installation documentation places the tool under the current user's local applications and creates desktop/start shortcuts. Verify the executable and settings after updates.
Open and focus Codex. The overlay may hide normally when Codex is closed, minimized or unfocused. Focus a real conversation window and verify the bar appears; complete or skip first-use guidance.
Adjust settings as needed. Click the gear to inspect version and placement. Preview appearance changes; Save and Cancel determine retention. Analytics and Context buttons are hidden by default and can be enabled in settings.

The repository offers a read-only diagnostic entry CodexUsageOverlay.exe --snapshot for window recognition and data sources. Report only necessary status/errors; avoid exposing email, quotas or token details. A running installer is only the first step; verify the actual window and data.

Understanding displayed results

Three data areas and their verification points
Display area	What it helps assess	How to verify
Account usage bar	Quota windows, remaining percentage, reset times and account status	Compare with local Codex quota windows. After login failures or incomplete fields, the tool may retain the last successful result; check status and update time.
Local session context	Context use, input/cache/output and cumulative tokens	Matches only a unique local session by current title; ambiguous names are not guessed. Records over 15 minutes old are labeled previous records; unmatched sessions show a waiting state.
Native analytics	Product/model usage, turns, skill and plugin calls	Seven- and 30-day windows end yesterday in UTC. Missing dates are not filled with zero; retain returned units and do not interpret percentages or turns as tokens.

Context use is not account quota or billing. Cumulative input already includes cache; do not add it twice. Missing cumulative values show "—" and cannot support cost, speed or turn estimates. Narrow panels or insufficient safe space may collapse or hide the bar to prevent obstruction.

Data sources and limits

Account quotas are read through the local Codex CLI app-server interface; task and context data come from local session events, token_count values and timestamps. Public documentation distinguishes these sources from real-time account billing.
Native analytics reads existing login state from CODEX_HOME/auth.json for fixed ChatGPT analytics requests in memory. It does not refresh/rewrite the shared auth file or upload local conversations. This internal client interface is not a stable public SDK; changes or outages produce errors.
Tibo reset forecasts come from a public unofficial status source and do not guarantee simultaneous delivery to every account. Forecasts or old caches cannot replace your own Codex quota response.
Window recognition, layout and login affect display. Record actual window state, data sources and errors when troubleshooting; sample screenshots or successful startup do not prove real data.
The project uses AGPL v3.0; read its license and third-party notices before distributing or modifying it. This article has not installed the tool, read your account or verified your desktop GUI.