Show five-hour and weekly usage in one Codex Meter widget

[kpadams94]

Baseline

This feature extends the existing Codex Meter defined in #1. Issue #1 remains the historical weekly-only MVP specification and is not rewritten by this work.

Codex account snapshots once again expose both a five-hour usage window and a weekly usage window. The current application intentionally selects only the weekly reading, so users cannot see the shorter allowance that may interrupt work first.

Problem statement

Codex Meter currently shows one remaining weekly percentage. A user can therefore appear to have ample weekly capacity while being close to exhausting the active five-hour allowance.

The user needs both remaining percentages visible at a glance without opening Codex, without creating a second desktop widget, and without making the existing ambient utility noisy or difficult to read.

Solution

Extend Codex Meter so its single bottom-right desktop widget contains two clearly labeled readings:

• 5 HR — remaining percentage in the approximately five-hour Codex usage window.
• WEEK — remaining percentage in the approximately weekly Codex usage window.

The final composition will be selected through a disposable visual prototype before production implementation. Both indicators use the same existing purple accent and retain the dark, translucent Quiet Card identity, but the current 143 × 49 dimensions and internal layout are not fixed.

User stories

1. As a Codex user, I want to see five-hour and weekly usage together, so I know which allowance is most likely to interrupt my work.
2. As a Codex user, I want both readings expressed as percentage remaining, so I do not have to invert percentage-used values.
3. As a Codex user, I want both readings in one desktop widget, so the utility remains compact and predictable.
4. As a Codex user, I want explicit 5 HR and WEEK labels, so I cannot confuse the readings.
5. As a Codex user, I want an unavailable reading identified honestly, so stale data is not presented as current quota.
6. As an existing user, I want my saved weekly reading to survive the upgrade, so startup remains useful while the first two-reading refresh runs.
7. As a Codex user, I want the tray summary to include both readings, so I can inspect usage from the Windows notification area.
8. As a Codex user, I want five-hour resets to remain quiet, so frequent short-window resets do not create notification noise.
9. As a Codex user, I want weekly reset notifications to continue working as before.
10. As a Codex user, I want the application to retain its clean single-file installation and normal Windows shortcut behavior.

Product decisions

• One Windows widget contains two rate-limit readings; this feature does not create two application windows or two independent widgets.
• Both readings show percentage remaining using clamp(100 - usedPercent, 0, 100).
• The visible labels are 5 HR and WEEK.
• Both indicators use the same purple accent. No distinct semantic colors or low-allowance traffic-light colors are introduced.
• A missing window renders as unavailable using a muted indicator and no numeric percentage.
• A valid reading still updates when the other reading is missing.
• An authoritative snapshot that omits a previously available window clears that window to unavailable rather than displaying its old value as current.
• Reset timestamps and countdowns remain hidden.
• The existing refresh schedule remains unchanged: startup, hourly, Windows wake, manual refresh, and passive Codex rate-limit updates.
• Hover continues to show one shared last-successful-check time because both readings come from one account snapshot.
• The system-tray tooltip summarizes both readings, for example: Codex Meter: 74% 5-hour · 42% weekly.
• Existing silent reset detection and notifications apply only to the weekly reading. Five-hour increases and resets never notify.
• The existing weekly notification threshold remains unchanged: an increase of at least ten points or a rise to 100%, excluding the first baseline.
• Failed account reads remain silent and preserve the last successful complete application state.

Data and compatibility decisions

• Continue reading the authoritative Codex account snapshot through account/rateLimits/read.
• Prefer rateLimitsByLimitId.codex, with the existing legacy Codex-bucket fallback.
• Classify readings by windowDurationMins, never by whether the value occupies primary or secondary.
• Recognize durations within approximately 5% of five hours or one week, following Codex's defensive duration-classification approach.
• Ignore unknown window durations and non-Codex buckets.
• Represent the account result as one snapshot containing optional five-hour and weekly readings plus one successful-check timestamp.
• Persist both optional readings and the shared check time in per-user application data.
• Continue loading the previous weekly-only JSON shape. Migrate its percentage into the weekly reading, leave the five-hour reading unavailable, and reconcile both with the normal startup refresh.
• Store no reset timestamps, account credentials, tokens, telemetry, or session-log data.

Prototype decisions

The final layout is deliberately unresolved until the prototype child issue is completed and reviewed.

The prototype must:

• adapt the earlier approved standalone HTML prototype rather than starting from a blank artifact;
• present three structurally different single-widget variants on one page;
• retain its desktop/taskbar context, URL-selectable variants, keyboard navigation, and floating variant switcher;
• allow independent adjustment of both percentages;
• include presets for ordinary, nearly depleted, fully available, five-hour unavailable, and weekly unavailable states;
• preserve the dark translucent card treatment and purple identity;
• use the same purple for both indicators;
• permit changes to dimensions, typography, CODEX label placement, progress geometry, and internal layout;
• keep both labels and readings visible without click or hover; and
• remain explicitly throwaway code that is not promoted directly into production.

The winning design must make both readings immediately identifiable, prevent confusion between them, remain unobtrusive, and keep normal, near-empty, full, and unavailable states legible.

Testing decisions

Production implementation must extend the existing acceptance seams rather than introduce credentialed or UI-scraping tests.

Coverage must include:

• five-hour and weekly readings in either primary/secondary position;
• modern multi-bucket and legacy Codex response shapes;
• approximate recognized durations and ignored unknown durations;
• either reading missing independently;
• conversion and clamping for both readings;
• partial authoritative snapshots clearing only the missing reading;
• migration from the weekly-only persisted JSON shape;
• first-ever startup, restored startup, successful reconciliation, silent failure, manual refresh, hourly refresh, wake refresh, and passive updates;
• weekly reset notification behavior remaining unchanged;
• five-hour increases and resets producing no notification;
• tray and accessibility text containing both readings; and
• rendered-widget states selected by the approved prototype, including 0%, 100%, and unavailable values without unintended wrapping or window resizing.

Packaging baseline

This feature must not regress the installation decisions established while completing #9:

• Release remains a self-contained single-file Codex Meter executable.
• Application and tray artwork remain embedded.
• The per-user installer remains named CodexMeter - Installer.exe.
• Installation continues under the user's Local AppData Programs directory.
• The installer continues creating a Codex Meter desktop shortcut, Windows startup registration, and a conventional uninstaller.
• Installed program files remain separate from persisted usage state.
• The change must not introduce a separate .NET prerequisite, loose runtime files, or unrelated installed artifacts.

Out of scope

• A second desktop widget or application window.
• Draggable or user-positioned placement.
• User-configurable labels, colors, dimensions, thresholds, or polling intervals.
• Different colors for the two readings.
• Reset timestamps, countdowns, or reset-time inference.
• Five-hour reset notifications.
• Changes to hourly/wake/manual/passive refresh scheduling.
• Credits, API billing, non-Codex limits, or plan-management UI.
• Installer redesign, auto-update, telemetry, analytics, or cloud storage.
• Promoting prototype code directly into the WPF application.

Delivery plan

1. Complete the prototype child issue and capture all three variants on a new throwaway prototype branch.
2. Record the user's selected direction and the reason it won on this issue.
3. Create a production implementation child issue with the approved visual contract and exact rendered-state acceptance criteria.
4. Implement the production feature by reauthoring the chosen direction in WPF with the repository's acceptance-test seam.

Further notes

• Original product baseline: Build Codex Meter, a tiny Windows weekly-usage widget #1
• Existing installer work: Install and start Codex Meter with Windows #9
• Earlier prototype source: prototype/approved-widget
• Current app-server contract: OpenAI Codex app-server README

[kpadams94]

Prototype #19 is ready for review on the throwaway branch: https://github.com/kpadams94/CodexMeter/tree/prototype/two-readings/prototype

It contains three deliberately different single-widget structures: A — Parallel rails, B — Twin orbits, and C — Bookend meters. Open prototype/index.html directly, use ?variant=A, ?variant=B, or ?variant=C, and exercise the external sliders, availability toggles, and six state presets.

Browser QA covered ordinary, near-empty, 0%, 100%, and either-unavailable states. All three variants kept fixed dimensions and bottom-right placement with no detected text clipping or reading overlap. No winner has been selected and none of this prototype code is production code.

[kpadams94]

Approved prototype direction: Variant C — Bookend meters.

Final review adjustment: reduce the outer width exactly 15%, from 218 px to 185.3 px. The approved direction keeps C's mirrored, bookended separation of 5 HR and WEEK while prioritizing a smaller ambient footprint.

Updated primary-source prototype: https://github.com/kpadams94/CodexMeter/tree/prototype/two-readings/prototype
Commit: a5727cd

This records the visual contract only. The production WPF implementation should reauthor the selected structure rather than promote the prototype code.