Build Codex Meter, a tiny Windows weekly-usage widget

[kpadams94]

Problem Statement

The user relies on Codex throughout the week but cannot see the remaining weekly usage allowance without opening Codex and locating its usage information. This makes it difficult to pace work and easy to discover a depleted allowance only when it becomes disruptive. Scheduled reset timestamps are insufficient because the production team may apply unscheduled or manual resets.

The user needs a tiny, ambient Windows indicator that remains visible during ordinary desktop work, obtains authoritative account usage directly from Codex, notices manual resets, and stays unobtrusive.

Solution

Build Codex Meter, a native Windows desktop utility that displays the remaining Codex weekly usage allowance in a compact, always-on-top widget anchored above the bottom-right taskbar area of the primary monitor.

The widget displays a compact percentage label and a slim purple progress bar. It performs a genuine account-level rate-limit read at startup, every hour, and immediately after the computer wakes. Between those checks, it accepts passive Codex rate-limit updates. It preserves the last successful value when a check fails and never derives a reset from a scheduled reset timestamp.

Codex Meter starts with Windows, hides while another application is full-screen, supports manual refresh from the widget, and provides a small right-click menu. A significant increase in remaining allowance produces a silent Windows notification.

User Stories

1. As a Codex user, I want to see my remaining weekly allowance at a glance, so that I can pace my work.
2. As a Codex user, I want the value expressed as a remaining percentage, so that I do not have to mentally invert a percentage-used value.
3. As a Codex user, I want the widget to remain in the bottom-right corner, so that its location is predictable.
4. As a Codex user, I want the widget above the taskbar work area, so that it does not cover Windows controls.
5. As a Codex user, I want the widget always on top during normal desktop work, so that applications do not obscure it.
6. As a Codex user, I want the widget hidden during full-screen applications, games, videos, and presentations, so that it does not cover immersive content.
7. As a Codex user, I want the widget to reappear after leaving full-screen mode, so that I do not need to reopen it.
8. As a Codex user, I want Codex Meter to start automatically when I sign in to Windows, so that it is always available.
9. As a Codex user, I want the installer to launch Codex Meter immediately after installation, so that I can verify it works.
10. As a Codex user, I want a fresh account check when the application starts, so that the saved value is promptly reconciled.
11. As a Codex user, I want a fresh account check every hour, so that manual production resets are detected even while Codex is idle.
12. As a Codex user, I want a fresh check immediately after Windows wakes, so that usage changes during sleep are detected.
13. As a Codex user, I want passive updates during Codex activity, so that the display changes sooner than the hourly check.
14. As a Codex user, I want hourly checks to read the current account state rather than infer it from a reset timestamp, so that unscheduled resets are reflected.
15. As a Codex user, I want the last successful value saved locally, so that the widget has useful information immediately after restart.
16. As a Codex user, I want the saved value displayed while the first fresh check runs, so that startup does not flash an empty widget.
17. As a Codex user, I want a first-ever launch state that clearly indicates checking until an initial value is available, so that a fabricated value is never shown.
18. As a Codex user, I want failed checks to leave the current value unchanged, so that temporary failures do not disrupt the display.
19. As a Codex user, I want failed checks to remain silent, so that network or authentication problems do not create noise.
20. As a Codex user, I want a failed hourly check to wait for the next hourly opportunity, so that the app does not enter a retry loop.
21. As a Codex user, I want to left-click the widget for an immediate fresh check, so that I can verify usage on demand.
22. As a Codex user, I want to right-click the widget for its menu, so that refresh, About, and Exit remain accessible without visible controls.
23. As a Codex user, I want Exit to close the app for the current Windows session only, so that it returns automatically after my next sign-in.
24. As a Codex user, I want hovering to show the time of the last successful check, so that I can judge the value's freshness.
25. As a Codex user, I want a silent notification when remaining allowance increases by at least ten percentage points or reaches 100%, so that I notice meaningful resets.
26. As a Codex user, I want notification clicks to do nothing beyond dismissal, so that Codex does not open unexpectedly.
27. As a Codex user, I want the reset notification to have no sound, so that it does not interrupt me.
28. As a Codex user, I want a very small widget, so that it consumes little screen space.
29. As a Codex user, I want the percentage label to remain on one line at 100%, so that the widget never expands due to wrapping.
30. As a Codex user, I want a slim purple progress bar, so that remaining usage is visually scannable while matching the approved design.
31. As a Codex user, I want the progress bar to remain purple at all levels, so that the appearance is consistent.
32. As a Codex user, I want the production progress bar to be display-only, so that accidental dragging cannot change the reported value.
33. As a Codex user, I want a system-tray icon, so that the running utility is recognizable and controllable.
34. As a Codex user, I want the tray and installer icon to be a purple meter ring with bold white “CM,” so that Codex Meter has a distinct identity.
35. As a Codex user, I want a normal per-user installer and uninstall entry, so that installation and removal follow Windows conventions.
36. As a Codex user, I want a small framework-dependent installation, so that the utility does not bundle a large copy of .NET already present on my computer.
37. As a Codex user, I want Codex Meter to reuse the existing Codex sign-in, so that I do not store or manage another credential.
38. As a Codex user, I want the application to store no separate OpenAI secrets, so that the utility does not add credential risk.
39. As a Codex user, I want Codex Meter to be Windows-only, so that implementation can prioritize reliable native desktop behavior.
40. As a Codex user, I want the application to avoid telemetry, so that this personal usage indicator remains private.

Implementation Decisions

• Build Codex Meter as a native, framework-dependent .NET 8 Windows desktop application using WPF.
• Treat this as a single-context application with distinct adapters around Codex account data, time/scheduling, persistence, Windows desktop state, notifications, startup registration, and the widget shell.
• Obtain authoritative usage through Codex app-server's account/rateLimits/read request.
• Receive passive changes through the app-server account/rateLimits/updated notification and merge/refetch according to the app-server contract.
• Do not scrape the visible Codex UI, browser state, session logs, or reset timestamp.
• Select the Codex weekly rate-limit window from the returned account snapshot. Convert usedPercent to remaining allowance with clamp(100 - usedPercent, 0, 100).
• Keep account integration behind a read-only usage-source interface so tests can supply controlled snapshots without authenticating to Codex.
• Reuse the existing local Codex authentication context. Never request, copy, persist, or display a separate account token.
• Coordinate startup, hourly ticks, wake events, passive updates, manual refresh, persistence, reset detection, and notification decisions through one application-session controller.
• Perform a fresh read immediately at application startup, every hour thereafter, immediately after system wake, and on left-click/manual refresh.
• After wake, restart the hourly schedule from the successful or attempted wake check.
• On a failed read, retain the current percentage and last-successful timestamp. Produce no error indicator, notification, or early retry.
• Persist only the last successful percentage and timestamp in per-user local application data.
• On first-ever launch without saved state, show a compact checking state until the first successful result; never invent a percentage.
• Compare each successful result with the previous successful value. Emit a reset notification when remaining allowance increases by at least ten percentage points or reaches 100%. Do not notify when establishing the first-ever baseline.
• A startup read may notify when it reveals a reset relative to a previously saved value.
• Use a silent Windows notification. Activating it performs no navigation or application action beyond dismissal.
• Implement a frameless, non-taskbar, topmost tool window anchored to the primary monitor's bottom-right work area.
• Recalculate placement when the primary work area or display metrics change, while preserving permanent bottom-right anchoring.
• Detect exclusive or borderless full-screen foreground applications and hide the widget until normal desktop mode returns.
• Use the approved “Quiet card” visual direction: 143-pixel outer width, 16-pixel corner radius, compact 10-pixel no-wrap percentage label, small CODEX label, and a slim inset progress bar.
• Keep the progress bar purple at every percentage. Production has no draggable preview behavior.
• Keep the widget compact at 0%, 100%, and every intermediate integer value; percentage text must not change window dimensions.
• Hover text contains only the last successful check time.
• Left-click performs a fresh read. Right-click exposes Refresh Now, About, and Exit.
• Exit terminates only the current process. Automatic startup remains enabled for the next Windows sign-in.
• Provide a system-tray icon and installer icon consisting of a purple meter ring with bold white CM.
• Register per-user Windows startup during installation and launch the application when installation completes.
• Produce a framework-dependent installer targeting 64-bit Windows and requiring the .NET 8 Desktop Runtime. The installer should detect a missing runtime and provide a clear prerequisite message rather than silently failing.
• Provide a conventional per-user uninstall entry that removes the application and startup registration.
• Run as a single instance so startup or repeated launches do not create duplicate widgets.
• Store no analytics or telemetry.

Testing Decisions

• Prefer one high application-session acceptance seam over many implementation-coupled unit seams.
• Run the complete session controller with controlled substitutes for the Codex usage source, clock/timer, persistence, Windows power/full-screen state, and notification sink.
• Tests assert external behavior: displayed state, account-read timing, persisted state, visibility, notifications, and user-command outcomes. They should not assert private method calls or class structure.
• Cover first-ever startup, startup with a saved value, successful and failed startup reads, hourly reads, failed hourly reads, wake checks, passive updates, and manual refresh.
• Cover conversion and clamping of used percentage to remaining percentage, including 0%, 1%, 99%, 100%, and invalid out-of-range inputs.
• Cover reset detection at below-threshold, exactly ten-point, greater-than-ten-point, and 100% transitions.
• Verify that the first-ever successful baseline does not notify and that a saved-value-to-startup-reset transition can notify.
• Verify notifications are silent and have no activation behavior.
• Cover entry to and exit from full-screen mode, including restoration to the bottom-right work area.
• Cover single-instance behavior and current-session-only Exit behavior.
• Add rendered-widget checks at representative values including 0%, 9%, 10%, 47%, 99%, and 100% to prove the label never wraps and dimensions remain constant.
• Add a Windows installation smoke test covering installation, immediate launch, startup registration, next-sign-in launch, and uninstall cleanup.
• This is a new repository, so there is no existing automated-test prior art. The approved visual prototype is the prior art for layout and percentage-state rendering.

Out of Scope

• macOS or Linux support.
• Mobile or browser versions.
• General ChatGPT message limits, API token billing, API credits, or non-Codex allowances.
• Multiple simultaneous rate-limit widgets.
• Draggable or user-positioned placement.
• Following the active monitor or selecting a secondary monitor.
• User-configurable colors, dimensions, fonts, thresholds, or polling intervals.
• Color changes at low allowance.
• Audible notifications.
• Opening Codex from a notification.
• Deriving resets from scheduled reset timestamps.
• Browser/UI scraping or direct reading of Codex session-log files.
• Separate OpenAI login or credential storage.
• Self-contained .NET deployment.
• Automatic application updating.
• Telemetry, analytics, or cloud storage.
• Production use of the prototype's drag-to-preview control.

Further Notes

• The approved UI prototype is preserved as a primary design source on the prototype/approved-widget branch: https://github.com/kpadams94/CodexMeter/tree/prototype/approved-widget/prototype
• The prototype is disposable and must not be promoted directly into production. Reimplement the approved decisions with production error handling and tests.
• The direct Codex app-server integration is preferable to reverse-engineered UI scraping, but it is still an integration boundary that may evolve with Codex. Keep protocol details isolated behind the usage-source adapter.
• The repository is private and uses GitHub Issues with the standard Matt Pocock triage-label vocabulary.