Building Usage Overlay for Codex on Windows

The main Codex usage limit matters while a developer is deciding how to spend the next block of work. Opening another screen to check it creates a small interruption at exactly the wrong time. Bringing the number closer, however, could not justify modifying Codex, scraping its rendered interface, or reaching into information the utility did not need.

Usage Overlay deliberately displays the main Codex limit. When App Server returns both primary and secondary windows for that limit, the detail card presents them as separate labelled rows. Spark and other model-specific buckets stay hidden so the account-level allowance remains easy to read.

The slim rail keeps the selected usage percentage visible. Hover opens the detail card and click pins it. The overlay does not claim access to quota totals that Codex App Server does not return.

The companion starts `codex app-server --stdio` as its own child process and communicates through newline-delimited JSON-RPC over redirected standard input and output. It refreshes account state through `account/read`, listens for `account/updated`, and then reads the current snapshot with `account/rateLimits/read`.

This lets sign-in, sign-out, and account switching update automatically without reading authentication files. The parser selects the main `codex` bucket, retains its primary and optional secondary window, and keeps model-specific buckets out of the display.

Usage Overlay runs as its own native Windows process. It does not modify Codex, inject code, inspect a rendered document, or take keyboard focus from the active app. Its WPF windows can accept pointer interaction while remaining non-activating, so the developer stays in the working context.

Codex CLI owns authentication, account state, and network access. Usage Overlay does not build a second sign-in flow or store Codex credentials.

The rail can anchor beside Codex, move in small X and Y steps, follow the app across monitors, or be dragged anywhere. At a custom position, the rail stays stationary while the detail popup expands upward and left on hover. The popup bottom aligns with the full rail, including its compact percentage label, so opening the card does not move the control under the pointer or leave the two surfaces visually disconnected. It can appear only with Codex or across Windows, hide for fullscreen work, pause for 15 minutes, return from the tray, and start with Windows. It also stays hidden while Codex-owned file picker, Open, and Save dialogs are active, so the overlay does not attach itself to a system dialog.

Dark, Light, and Follow Codex appearance modes keep the utility legible without capturing or storing screen content. The interface uses solid GPU-safe WPF surfaces rather than backdrop blur.

A stale percentage is more misleading than an empty one. Version 0.3.1 clears the previous account’s value after sign-out or an account switch, then reloads the active account. Account changes are detected from login-file timestamps and size only; credential contents are not read. Routine polls no longer force token refreshes, and stalled requests reconnect after 30 seconds.

Disconnect Codex CLI releases only the App Server process tree the utility started. Threshold notifications remain optional and off by default, and update checks remain manual.

General, Visibility, Position, Appearance, and Connection & diagnostics controls live in one native window. Most changes are staged until Save or Ctrl+S. Cancel and Escape discard unsaved changes, while validation covers the warning thresholds, custom CLI path, and refresh interval.

The rail and tray menus expose the manual GitHub update check and the safe disconnect or reconnect action, so recovery and maintenance do not require editing a file or killing an unrelated process.

Usage Overlay requests account state and rate-limit metadata through documented App Server methods. It does not request prompts, responses, conversation history, repository files, browser activity, cookies, passwords, API keys, or Codex authentication-file contents. Codex remains the owner of authentication and account-data network access.

Preferences are stored in `%LOCALAPPDATA%\UsageOverlay\settings.json`, and redacted diagnostic messages are written to `%LOCALAPPDATA%\UsageOverlay\overlay.log`. Optional installation reporting is off unless enabled; it sends a random installation ID and app version, never account or quota data. There is no analytics SDK, advertising, crash reporting, network listener, automatic updater, or separate account system. Cursor support is not part of the current public release.

The v0.3.1 release passed a zero-warning Release build, all 18 core specifications, isolated account-switch regression checks, authenticated usage and reconnect checks, and package validation. The regressions covered signing out, switching accounts, clearing the old snapshot, and preventing late replies from restoring previous-account usage.

The previous v0.3.0 release also verified optional-reporting consent, payload scope, local persistence, daily limits, failure behavior, and cancellation. Those checks remain part of the public release history; this case study does not claim a new production or adoption metric.

The per-user setup package installs Usage Overlay without administrator access, creates the normal Windows Search and Start Menu entry, and registers a standard uninstaller under Settings → Apps → Installed apps. The portable ZIP remains available for users who do not want an installed application.

Installer verification covered install registration, installed-file presence, application launch, uninstall execution, and cleanup of registration, application files, and shortcuts. Local settings and redacted logs are deliberately preserved for a later reinstall.

Packaging creates the Windows x64 setup executable, portable ZIP, release manifest, and SHA256SUMS file. Usage Overlay v0.3.1 is publicly released from commit `42a11ca`. Its installer and ZIP, release manifest, and checksums are available from the public release. The downloads remain unsigned, so SmartScreen and checksum guidance remain part of the installation path.

The public repository includes the MIT licence, architecture and privacy documentation, security and support policies, contribution guidance, CI, CodeQL, issue templates, and the release tooling.

The verified outcome is a publicly available Windows companion that keeps the main Codex limit visible, detects account changes, separates primary and secondary limit windows when returned, and clears stale data during sign-out or switching. It keeps Codex credential contents and conversations outside its scope. Settings and redacted logs remain local; optional installation reporting sends only a random ID and app version after consent.

Version 0.3.1 is available as an unsigned Windows x64 installer and portable ZIP with published checksums. Cursor support is being evaluated and is not included in this release. This outcome does not imply adoption, download numbers, revenue, productivity gains, time savings, or an official OpenAI partnership.