Building Usage Overlay for Codex on Windows

Codex usage data matters while a developer is already deciding how to spend the next block of work. Opening another screen to check it adds a small interruption at exactly the wrong time. But bringing the number closer could not justify an unsafe dependency on the Codex desktop interface. Modifying the app, injecting code, or scraping its rendered document would be fragile, unsupported, and too close to information the utility did not need.

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

Authentication and account ownership remain with Codex CLI. The companion asks for rate-limit metadata through the existing signed-in Codex connection and does not build a second account or credential flow around it.

The first number answers the practical question: how much usage is left? A slim rail uses green, amber, and red thresholds, with a compact percentage below it. Hover opens the reset-time detail card, and click pins it when the information needs to stay visible. The close button and Escape dismiss the card without stopping the app.

If there is no fresh value, the rail switches to a neutral state and shows “--”. An extra Spark row was removed from the card because it competed with the remaining percentage, reset time, and connection status without helping the immediate decision.

The companion starts `codex app-server --stdio` and communicates through newline-delimited JSON-RPC over redirected standard input and output. It initializes the server, reads the current snapshot with `account/rateLimits/read`, and listens for `account/rateLimits/updated` notifications.

Live notifications update the rail quickly. Configurable polling remains as a fallback, so a missed notification does not leave the display disconnected from the next available snapshot.

A stale percentage is more misleading than an empty one. When the connection fails or stops producing a fresh snapshot, Usage Overlay clears the old number instead of presenting it as current. The rail stays neutral until valid rate-limit data returns.

The rail can anchor to the left or right edge of Codex, move in X and Y steps, reset to its default position, or be dragged anywhere and saved with relative coordinates. Multi-monitor tracking follows Codex when its window moves between displays.

Visibility can be limited to Codex or kept across Windows. The overlay can hide in fullscreen, pause for 15 minutes, return from the system tray, start automatically with Windows, and recover an existing process when launched again instead of creating a duplicate instance.

Appearance can follow Codex or stay in a fixed Dark or Light mode. When Follow Codex is selected, the app samples a few rendered background pixels to infer whether the surface is light or dark. It does not save or log screen content, and it falls back to the Windows application theme when Codex is unavailable.

The interface uses solid, GPU-safe WPF surfaces. There is no backdrop blur or simulated glass effect competing with window movement and desktop rendering.

Settings are grouped into General, Visibility, Position, Appearance, and Connection & diagnostics. Most changes are staged until Save is chosen or Ctrl+S is pressed. Cancel and Escape discard unsaved changes. The minus button hides Settings only, while the close button discards unsaved changes and leaves the overlay running.

Theme choices preview immediately and roll back if the window is cancelled. Validation covers amber and red thresholds, the custom CLI path, and the refresh interval. Restore defaults stages the original values so they can still be reviewed before saving.

Usage Overlay reads rate-limit metadata only. It does not request prompts, responses, conversation history, repository files, browser activity, cookies, passwords, API keys, or Codex authentication files. Codex CLI owns authentication and network access.

Local preferences are stored in `%LOCALAPPDATA%\UsageOverlay\settings.json`, and redacted diagnostic messages are written to `%LOCALAPPDATA%\UsageOverlay\overlay.log`. The app has no telemetry, advertising, analytics SDK, network listener, or separate account system.

The automated suite contains 11 dependency-free specifications for parsing, partial updates, percentage handling, reset formatting, status thresholds, settings normalization, log redaction, and legacy settings. Release builds treat warnings as errors and verify that the Windows icon contains the expected sizes. An authenticated smoke test starts App Server, waits for real rate-limit data, reports the result, and closes its child process.

Demo modes cover green, amber, and red states without requiring an account connection. The manual matrix checks hover, pin, drag, themes, fullscreen behavior, monitor movement, startup, persistence, and duplicate-process recovery. GitHub CI and CodeQL run against the public source.

Publishing the code meant preparing more than the executable. The public repository includes the MIT licence, README and banner, architecture and privacy documentation, security and support policies, a contribution guide, issue and pull-request templates, and Dependabot configuration.

PowerShell scripts cover building, packaging, release validation, live smoke testing, icon verification, Windows shortcuts, startup, and removal. The repository makes the product boundary and the work needed for a future release visible before claiming that a downloadable release is complete.

The verified outcome is a working, publicly reviewable Windows companion for Codex usage. It keeps the main remaining percentage visible, provides a compact reset-time view, follows Codex across common desktop states, handles missing data without showing stale numbers, and keeps authentication and conversation data outside its scope.

That outcome does not imply user adoption, download numbers, revenue, productivity gains, time savings, an official OpenAI partnership, or a completed downloadable release.