Feature request: calendar month-to-date option for the cost reporting period

[kcharlan]

Problem

Cost reporting (menus, inline dashboards, cost submenus/charts, widgets, and codexbar cost) is always a rolling
last-N-days window. Many of us budget against calendar months — provider billing cycles, employer expense periods,
and personal budgets all reset on the 1st — so "spend in the last 30 days" and "spend this month" can differ
substantially mid-month. There's currently no way to see month-to-date cost without exporting and computing it
externally.

Related precedent: #689 established calendar-month pacing for Copilot premium usage. This proposal generalizes the
same idea to the shared cost reporting period.

Proposed behavior

Add a user-selectable cost reporting period with two modes:

• Rolling last N days (current behavior, remains the default — no change for existing users)
• Month to date (current local calendar month, resolved against a per-operation "now" rather than a cached
  startup clock)

The saved selection applies consistently everywhere a cost period is shown or computed: shared cost menus, inline
dashboards, cost submenus and charts, widgets, CLI default output, project breakdowns, labels, and totals.

CLI precedence: an explicit codexbar cost --days N always selects a rolling N-day window and overrides the saved
month-to-date setting, so scripts keep deterministic behavior.

Design considerations (from a working prototype implementation)

I have this implemented and validated in a prototype. The sharp edges this surfaced:

1. Cache identity must include the semantic window. Fetch and /cost serve-cache keys need the resolved period
   (e.g. calendar-month:2026-07) so a mode switch never relabels data fetched for a different window, and failed
   refreshes must not strand the new period with a stale snapshot from the old one.
2. Provider aggregation must be window-aligned. Totals, tokens, requests, charts, and top-model facts should all
   derive from entries in the same resolved window. Providers that return pre-aggregated values (e.g. Mistral) need
   to recompute aggregates from daily buckets when a sub-window is selected.
3. JSON/API compatibility. Existing last30Days... JSON field names can remain as compatibility aliases while
   new period-neutral names are introduced, so downstream consumers (Waybar/GNOME/KDE integrations, showy-quota)
   don't break.
4. Widget/app localization parity. The period labels ("Month to date", etc.) need matching entries in both the
   app and widget-extension locale catalogs across all 23 locales.

I suggest focused test coverage for the period resolver, CLI precedence, serve-cache identity, and widget
snapshot/localization behavior.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 22, 2026, 7:18 PM ET / 23:18 UTC.

Summary
Current main still supports rolling cost windows only. This remains a new, cross-surface reporting contract that needs maintainer product direction before implementation.

Reproducibility: not applicable. this is a new reporting mode, and current source confirms the supported behavior is rolling 1...365-day windows.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Maintainer decision needed

Question	Recommendation
Should CodexBar add a persisted calendar month-to-date cost period, and should the first release cover every shared cost consumer or only a defined subset?	Approve a complete shared contract: Define month-to-date as one persisted option across all cost surfaces, retain rolling days as the default, and preserve an explicit CLI rolling override.

Why: The request adds a user-visible setting and shared semantics across scans, caches, aggregation, widgets, JSON, and CLI; VISION.md requires sign-off for this scope.

Next step
A sponsor must choose the user-facing scope and compatibility contract before the older prototype can be safely rebased.

Review details

Best possible solution:

Approve one shared period contract, then add a period resolver and cache identity across every selected cost consumer while preserving rolling output and JSON compatibility.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a new reporting mode, and current source confirms the supported behavior is rolling 1...365-day windows.

Is this the best way to solve the issue?

Unclear until scope is approved: a shared period resolver is safer than per-view calendar logic, but maintainers must decide which consumers participate in the first release.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A partial rollout could present inconsistent periods across menus, dashboard, widgets, JSON, and CLI, or reuse a snapshot obtained for a different window.

Codex review notes: model internal, reasoning high; reviewed against 27c7f334e3c4.

Label changes

Label justifications:

• P3: This is an optional reporting enhancement, not broken behavior with an established contract.
• impact:ux-friction: Users who budget by calendar month currently need an external calculation to compare CodexBar costs with their billing period.

Evidence reviewed

What I checked:

• Rolling setting only: The persisted cost setting is an integer constrained to 1...365 days, with no calendar-period mode. (Sources/CodexBar/SettingsStore+Defaults.swift:577, 27c7f334e3c4)
• Dashboard choices: The shared Usage & Spend dashboard exposes only 7, 30, 90, and 365-day ranges. (Sources/CodexBar/PreferencesSpendDashboardPane.swift:221, 27c7f334e3c4)
• CLI contract: The CLI documents --days as a rolling 1...365-day cost-history window and clamps the parsed value accordingly. (Sources/CodexBarCLI/CLICostCommand.swift:565, 27c7f334e3c4)
• Cache and period-owner history: Recent commits show active ownership of the two central paths: spend-dashboard model construction and profile-scoped token-cost snapshot isolation. (Sources/CodexBar/UsageStore+TokenCost.swift:342, 5bc78a2c309b)
• Product-direction policy: VISION.md says new features and changes adding meaningful maintenance complexity need sign-off; this proposal adds a persisted, shared reporting contract. (VISION.md:11, 27c7f334e3c4)

Likely related people:

• Yuxin Qiao: Recent main history includes the spend dashboard’s parallel-load and model-build work, a central consumer of any shared period semantics. (role: recent spend-dashboard contributor; confidence: medium; commits: 1cf98b330a79; files: Sources/CodexBar/SpendDashboardController.swift)
• Peter Steinberger: Recent main history includes profile-scoped token-cost snapshot isolation, directly adjacent to cache identity for a new period mode. (role: recent token-cost cache contributor; confidence: medium; commits: 5bc78a2c309b; files: Sources/CodexBar/UsageStore+TokenCost.swift)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[dpanshug]

Interest / offer to help

I hit the same gap: Usage & Spend and cost surfaces only expose rolling windows (7d / 30d / last-N-days), so mid-month “budget vs calendar month” still needs an external calc.

I read the ClawSweeper review and agree this needs a maintainer product decision before a code PR — especially given VISION.md (“new features need sign-off”) and the cross-surface contract called out here (settings, cache identity, aggregation, widgets, CLI --days override, JSON aliases).

Questions for maintainers

1. Is a persisted Month to date reporting period something you want in product, with rolling days remaining the default?
2. Preferred scope for a first ship:
   • A) full shared period contract as described in this issue, or
   • B) a narrower first cut (e.g. Usage & Spend / cost menus only), with CLI/widgets/JSON follow-ups?

I’m happy to implement once there’s a clear “go” on shape. Happy to align with @kcharlan’s prototype rather than redoing work — if that prototype is shareable (branch/gist/diff), I can help turn it into a Fixes #2087 PR under whatever contract you approve.

No pressure if this stays P3 / deferred; mainly looking for a sponsor decision so contributors don’t open a premature PR.

[kcharlan]

Thanks! I can share the prototype. It was implemented and validated against v0.42.1, but it has not been forward-ported to current main. I’m attaching a source-only patch bundle with the tests and implementation notes. Please treat it as design/reference material rather than a clean current-main patch. Given the pending maintainer product decision, I’d prefer to defer a full rebase until the desired product contract is approved.

Bundle contains:

• README.md
• calendar-month-reporting-v0.42.1.patch
• implementation-notes.md
• file-list.txt
• SHA256SUMS.txt

Validation completed:

• Patch applies cleanly to upstream v0.42.1.
• 100 changed paths; 210 KB patch.
• Focused feature tests: 114 passed.
• Full suite: 633 selections across 53 groups passed without retries or timeouts.
• make check passed.
• Checksums verified.

CodexBar-calendar-month-prototype-v0.42.1.zip

[dpanshug]

@clawsweeper how can we ask this to maintainer?