Skip to content

Subscription Utilization History#565

Open
maxceem wants to merge 47 commits intosteipete:mainfrom
maxceem:feature/usage-history
Open

Subscription Utilization History#565
maxceem wants to merge 47 commits intosteipete:mainfrom
maxceem:feature/usage-history

Conversation

@maxceem
Copy link

@maxceem maxceem commented Mar 18, 2026

Pain Point

  • At the moment I can only see the utilization level of the current session and current week.
  • But once week is finished I cannot see how much of token did I utilized previous week and how much wasted.
  • I cannot get the past data form the websites of the Codex and Claude too.

Solution

Add Subscription Utilization menu item which would show history of subscription utilization history:

  • sessions history
  • weekly history
Screenshot 2026-03-20 at 12 53 22

Features

  • Supported providers:
    • Codex
    • Claude
    • code made with though of supporting other providers
  • History is tracked per account. So we can switch between accounts inside providers and history would be shown for that account.
  • Extra usage is NOT counted towards subscription utilization. Because our aim is to understand how well we used "prepaid" tokens, not tokens on demand.
  • Subscription utilization shows chart with the same name as main bar:
    • Session

      image
    • Weekly

      image
  • Each bar on the carts represents one reset window. The time of each bar is "reset at" time.

Implementation Details

  • To keep solution flexible, the raw data provided by provider is stored in history files, so it could be displayed in any shape we want later if we want to change it. The data stored:
    • limit name: "session", "weekly". With potential support of other limit names like "codeReview" for Codex or "mcp" for Z.AI.
    • windowMinutes - 5-hour window, 7-days window and so on
    • resetAt - time when this limits resets
    • usagePercentage - how much of limit has been used
    • capturedAt - time when snapshot was captured
  • History is retained for approximately 2 years even though now we show maximum 30 weeks, maybe we will want to show more data later.
  • Samples are recorded at most once per hour.
  • History is persisted as one JSON file per provider.
  • At the current retention limit, the maximum history file size per account with 2 years of data is roughly 4.5 MB. So for example, a user with 10 accounts would use up to roughly 45 MB of disk space after 2 years of usage.

We treat email-based accounts and token-based accounts as separate

We keep identity-derived history and token-account history separate on purpose. Email is not a safe bridge key because one email can map to multiple token accounts, and we do not currently have a verified per-account ID to merge them safely.

We prioritize data with reset time over data with higher usage during the same period as more trustworthy

Within an hour bucket, we prioritize entries with resetsAt set. The first reset-backed sample replaces earlier provisional data without reset metadata, later same-hour samples can still raise usage under that boundary, and we only split when known reset times materially differ.

If there were no data for some period we show this bar as 0

But still when hover, show in details for the bar, that there is actually no data.

Limitations

1. CodexBar has to be run to gather Subscription Utilization history

User has to open CodexBar at least each reset 5-hour or 7-days period when Codex/Claude was used - then this period would be recorded in the history and took into account. If during one reset period user used Codex/Claude but didn't open CodexBar, then usage for that reset period would not be recorded and thus history chart would show lower usage.

2. When multiple accounts used per provider, history might get attached to wrong accounts

This limitation is caused by existent issue - sometimes identity of connected account (especially often happens with Claude) is not recognized by CodexBar and then we don't know to which account current usage data belongs to.

  • This can only happen when multiple Claude/Codex accounts are used.
  • This can only happen when the active Claude/Codex account is not fully identified (especially often happens to Claude), for example when CodexBar shows the Claude account without an email address.
  • In that state, CodexBar has usage data but does not have enough identity information to know which account the data belongs to.
  • Current workaround:
    • If the account is not identified, CodexBar attaches history to the last account that was previously identified for the current provider.
    • On a fresh install, if no account has been identified yet, CodexBar first records history in an anonymous bucket. As soon as the first account is identified for the provider, all previously recorded anonymous history is attached to that account.

PS: I did quite a lot of changes and final fixes to my code for this PR. So even though I've tested all of them, I didn't have a chance to test new fixes for some longer period of time. Thus, please, treat this feature as beta/experimental.

# Conflicts:
#	Sources/CodexBar/StatusItemController+Menu.swift
# Conflicts:
#	Sources/CodexBar/UsageStore.swift
- Store plan utilization history in per-account buckets plus unscoped fallback
- Hash provider identity fields for stable account keys when selecting history
- Add v2 persistence with legacy file migration and round-trip coverage in tests
- Use token-account-derived bucket keys for plan history when available
- Fall back to identity keys for legacy/snapshot-only samples
- Add tests for bucket selection, legacy isolation, and recording behavior
CodexBar 0.18.0

# -----BEGIN SSH SIGNATURE-----
# U1NIU0lHAAAAAQAAADMAAAALc3NoLWVkMjU1MTkAAAAgj1exoJyvxMic+cdy5NV+9ddyyh
# QWs4TuZ6d9sQgcVb0AAAADZ2l0AAAAAAAAAAZzaGE1MTIAAABTAAAAC3NzaC1lZDI1NTE5
# AAAAQJfvE7OiLkwZ3EKX5j1pYVeGfrixG8HoUhLColkyjtZNKN8CIDfypaCpu2uRCp0kt8
# KEid8oy054J/V6gGSuhQs=
# -----END SSH SIGNATURE-----
# gpg verification failed.

# Conflicts:
#	Tests/CodexBarTests/StatusMenuTests.swift
- Prefer the active token account when recording plan utilization without an explicit account
- Update Claude plan-utilization test to assert writes land in the selected token bucket
- Convert test method names to backticked descriptive phrases
- Remove redundant `@Suite` annotation from `StatusMenuTests`
- Delete outdated Codex usage history submenu test
- Display "Refreshing..." in usage history chart when a provider refresh is in progress and no samples exist
- Prevent Claude plan utilization reads/writes when identity/account key is unavailable
- Add tests for empty-state messaging and Claude/Codex history fallback behavior
- Save a plan-utilization history sample after successful selected-account fetches
- Add coverage to ensure selected Claude token accounts write to scoped history buckets
- Merge same-hour plan utilization updates instead of appending duplicates
- Preserve newer values when stale concurrent writes arrive
- Add tests for hour-bucket coalescing, stale-write handling, and concurrent writes
- Store plan utilization as primary/secondary windowed samples with reset timestamps
- Select visible chart periods from available window data and derive buckets when exact-fit data is missing
- Parse and propagate reset dates/window lengths from Claude and Codex status snapshots
- Split derived history into time intervals and weight bucket contributions by overlap
- Normalize daily/weekly/monthly derived values against full bucket duration
- Update utilization chart tests to assert the new normalization behavior
- Backfill daily/weekly/monthly chart buckets through the current reference period
- Add trailing zero bars up to the reference day for sparse daily history
- Update utilization history tests to cover gap-filling behavior
- Use reset timestamps as exact-fit bar dates when reset boundaries exist
- Fill missing and trailing weekly reset periods with zero-value bars
- Add focused tests for same-day shifts, cross-day resets, and gap handling
- Route Claude credentials via explicit planning (OAuth/web cookie/manual) and plan-aware settings snapshots
- Move Claude debug logging into focused helpers with timeout protection and preserved task-local test context
- Add coverage for credential routing/source planner behavior and refresh/debug diagnostics
- Add Claude-specific account-key resolution with bootstrap anonymous bucket migration
- Persist preferred account key in plan history schema v4 for sticky fallback behavior
- Hide Claude history only during true initial refresh and expand test coverage for identity/account flows
maxceem added 7 commits March 18, 2026 10:21
- Replace Claude-only bootstrap account handling with shared unscoped history adoption
- Resolve plan history buckets via provider-agnostic account key logic
- Add/adjust tests for Codex identity resolution and fallback to last resolved account
- Show used and wasted percentages on one detail line in the history chart
- Add provenance text for exact-fit vs derived aggregation sources
- Add tests for derived detail text and exact-fit provider-reported copy
- Merge plan utilization samples only when window/reset markers are compatible
- Pick merge candidates around insertion point to handle late backfills deterministically
- Add reset coalescing tests for primary/secondary boundary changes and chart behavior
- Record plan utilization history for non-selected token accounts after refresh
- Add flags to avoid updating preferred account key from secondary samples
- Prevent secondary Claude samples from consuming/adopting unscoped bootstrap history
- Add Claude identity tests covering preferred-bucket and bootstrap edge cases
- Move Codex credit refresh and snapshot-backfill logic into `UsageStore+CodexRefresh`
- Adjust member visibility so the new extension can reuse cached credits and backfill task state
- Expect same-hour backfills to be ignored when they would overwrite later-window values
- Keep stale same-hour samples with different window markers as separate history entries
- Update chart/detail assertions to match two-point aggregation and revised date formatting
Copy link

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 267a2ab817

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

maxceem added 2 commits March 18, 2026 15:31
- infer boundary dates for samples that omit `resetsAt` using observed reset cadence
- prefer real upcoming reset anchors over projected cadence when both exist
- add weekly exact-fit tests for missing reset, shifted anchor, and restored cadence scenarios
# Conflicts:
#	Sources/CodexBar/StatusItemController+Menu.swift
@maxceem
Copy link
Author

maxceem commented Mar 18, 2026

@codex review

@chatgpt-codex-connector
Copy link

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

@o1xhack
Copy link

o1xhack commented Mar 19, 2026

@codex review

Copy link

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 55fd6f51a7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

- Record Codex utilization history using each snapshot's `updatedAt`
- Keep refresh and backfill entries aligned to actual sample time
@maxceem maxceem marked this pull request as draft March 19, 2026 10:31
@maxceem maxceem changed the title Subscription Utilization History Subscription Utilization History [don't merge yet] Mar 19, 2026
maxceem added 7 commits March 20, 2026 12:00
- Replace period-based chart selection with dynamic visible series filtering
- Rework point generation to align on reset boundaries and fill missing windows
- Simplify chart detail/axis rendering and update plan utilization tests
- Persist plan history as one JSON file per provider under `history/`
- Add migration script to convert legacy `plan-utilization-history.json`
- Update tests and test store wiring for directory-based history storage
- Replace provisional hourly peak when a later sample adds first known `resetsAt`
- Preserve promoted reset boundary when later same-hour samples update usage
- Add regression tests for reset-boundary promotion and coalescing behavior
- Reuse `makeMenuCardItem` for Subscription Utilization with configurable chevron alignment/padding
- Switch Credits/Usage/Cost history entries to plain `NSMenuItem` submenu rows
- Simplify usage breakdown submenu creation and add a dedicated hosting view for usage history
- Remove chart-level "Refreshing..." empty state in favor of series-specific no-data messaging
- Hide plan utilization history submenu during refresh when no snapshot is available
- Add tests for menu visibility and updated empty-state behavior
@maxceem maxceem marked this pull request as ready for review March 20, 2026 07:57
Copy link

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c4b0ca08eb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

@maxceem maxceem changed the title Subscription Utilization History [don't merge yet] Subscription Utilization History Mar 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants