feat(claude): expose saved usage-limit resets in CLI JSON

[materemias]

Request

Expose Claude Code's saved usage-limit reset grants in codexbar usage --provider claude --source oauth --json, analogous to the existing Codex usage.codexResetCredits output. This would let CLI consumers display the remaining resets and earliest expiration without making a second authenticated request.

Data source and observed response

Claude Code 2.1.280 requests GET https://api.anthropic.com/api/oauth/usage?cedar_ember=1&skip_spend=1 with its OAuth bearer token, anthropic-beta: oauth-2025-04-20, and a Claude Code CLI User-Agent. The regular /api/oauth/usage response had cedar_ember: null for the account tested. The opt-in query returned a cedar_ember object. Requests with a generic/claude-code/<version> User-Agent returned eligible: false, ineligible_reason: "surface", and no grants; claude-cli/2.1.280 (external, cli) returned an eligible grant. Please check the appropriate supported client identity rather than assuming the normal usage fetch is enough.

Relevant fields, with account-specific values omitted:

{
  "cedar_ember": {
    "eligible": true,
    "grants": [
      {
        "id": "<grant id>",
        "label": "<description>",
        "resets_total": 1,
        "resets_left": 1,
        "starts_at": "<ISO timestamp>",
        "ends_at": "<ISO timestamp>",
        "clears": ["five_hour", "seven_day"],
        "paused": false,
        "usable_now": true,
        "use_requires_limit": false
      }
    ],
    "next_grant_id": "<grant id>"
  }
}

The grant count is resets_left (not simply the number of grants); ignore paused, not-yet-started, expired, and exhausted grants for an available count. usable_now/use_requires_limit describe whether redemption is currently allowed and should not be conflated with saved credits remaining. Expose expiry and the applicable clears windows where possible. Absent/ineligible grants should not be reported as available. This is a read-only request; no redemption action is needed.

Current gap

In CodexBar CLI 0.64.1, Claude OAuth JSON contains usage windows but no saved-reset grants, while Codex already includes codexResetCredits. The upstream OAuth response decoder currently omits cedar_ember: Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthUsageFetcher.swift. A KDE CLI consumer currently has to make this extra request itself to show Claude's saved resets. Reusing the existing OAuth credential and rate-limit handling in CodexBar would avoid duplicating authentication and HTTP behavior in each client.

[clawsweeper]

Codex review: this still needs some work. Reviewed September 23, 2026, 4:15 AM ET / 08:15 UTC.

Summary
Keep open: current main and v0.65.0 lack this concrete provider-data capability. The request fits CodexBar’s scope, but new-feature sign-off and a supported client identity remain unresolved.

Reproducibility: not applicable. as a bug reproduction: this requests new output. Source confirms the omission, while the reported upstream grant eligibility has not been independently exercised.

Maintainer decision needed

Question	Recommendation
Should CodexBar add read-only Claude reset inventory to CLI JSON, conditional on validating the supported request identity and preserving existing usage data?	Sponsor the bounded addition: Approve read-only inventory support after validating the request identity and choosing an additive JSON contract.

Why: VISION.md requires new-feature sign-off, and the reporter’s client-identity-dependent result leaves a provider contract choice that source inspection cannot settle.

Next step
Obtain feature sign-off and settle the supported request identity and JSON contract before implementation; this is not an automatic bug-fix candidate.

Review details

Best possible solution:

Provide additive, provider-scoped reset inventory through the shared OAuth pipeline, preserving spending and rate-limit behavior and separating saved balance from immediate redemption eligibility.

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

Not applicable as a bug reproduction: this requests new output. Source confirms the omission, while the reported upstream grant eligibility has not been independently exercised.

Is this the best way to solve the issue?

Yes, reusing the shared OAuth pipeline is the appropriate direction; the exact client identity and JSON representation need approval, and copying skip_spend=1 unconditionally could remove existing information.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The reported surface-dependent eligibility requires verification of a supported CodexBar client identity before adopting the request.
• The proposed request includes skip_spend=1; implementation must establish that requesting grants preserves existing Claude spending output.

Codex review notes: model internal, reasoning medium; reviewed against 83afdb7dbff0.

Label changes

Label changes:

• add P2: This is a bounded provider-data improvement for CLI consumers, with no established outage or broken existing contract.
• add impact:other: Consumers currently need an additional authenticated request to display Claude’s saved reset inventory.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P2: This is a bounded provider-data improvement for CLI consumers, with no established outage or broken existing contract.
• impact:other: Consumers currently need an additional authenticated request to display Claude’s saved reset inventory.

Evidence reviewed

What I checked:

• Current request and decoder omit grants: The request uses /api/oauth/usage without query parameters, constructs a claude-code/version User-Agent, and decodes usage windows, extra_usage, and limits without cedar_ember. The existing rate-limit gate already wraps this request. (Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthUsageFetcher.swift:77, 83afdb7dbff0)
• JSON boundary confirms the missing capability: ClaudeUsageFetcher.mapOAuthUsage maps windows and spending into ClaudeUsageSnapshot without saved grants. UsageSnapshot encodes codexResetCredits but has no corresponding Claude inventory; CLI ProviderPayload serializes this shared snapshot. docs/cli.md also documents usage.details as the existing generic provider-information surface, which should be considered when choosing the output contract. (Sources/CodexBarCore/UsageFetcher.swift:358, 83afdb7dbff0)
• Useful reporter observations: The supplied issue body includes a redacted grant shape, distinguishes resets_left from grant count and redemption eligibility, and reports that the opt-in request succeeds only with a different client identity. These observations make the proposal concrete, but the upstream eligibility contract has not been independently verified. The captured discussion contains no human response or linked implementation.
• Product scope and sign-off: VISION.md includes provider credits and reset windows, keeps provider fetching/authentication in shared core/CLI, and explicitly requires sign-off for new features. External KDE presentation is separate, but supplying its provider data belongs within the documented core boundary. (VISION.md:15, 83afdb7dbff0)
• Latest release still lacks support: GitHub identifies v0.65.0 as the latest release, published September 23, 2026. Its dereferenced commit is 20a70d9. Reading its Claude OAuth fetcher and comparing it with HEAD showed the same request and decoder, with no changes between those revisions. (Sources/CodexBarCore/Providers/Claude/ClaudeOAuth/ClaudeOAuthUsageFetcher.swift:261, 20a70d955d47)
• Related-work search: GitHub searches for Claude reset inventory, saved resets, and cedar_ember found no verified canonical implementation or duplicate. The cedar_ember search returned only this issue; broader matches concerned other reset, display, or synchronization behavior.

Likely related people:

• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)

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.

[steipete]

Existing usage-window reset timestamps are already emitted in CLI JSON when available. The current Claude snapshot has no separate saved usage-limit reset inventory. Please identify the corresponding app field or provide a redacted source response and expected JSON fields so an additive contract can be established.

[materemias]

Those are the window resetsAt timestamps. I mean something else: the saved reset grants in Claude Code, which you spend to clear the 5h and weekly windows early. In 0.65.0 the Claude usage object has only extraRateWindows, identity, loginMethod, primary, secondary, tertiary, updatedAt, so these grants aren't in the output.

Source. It's the same OAuth usage request with two changes. Add ?cedar_ember=1 to the query and send User-Agent: claude-cli/2.1.280 (external, cli). With the current claude-code/<version> UA the block comes back as eligible: false, ineligible_reason: "surface". Don't add skip_spend=1, because it sets extra_usage to null.

Redacted response:

"cedar_ember": {
  "eligible": true,
  "grants": [{
    "id": "<redacted>",
    "label": "<redacted>",
    "resets_total": 1,
    "resets_left": 1,
    "starts_at": "2026-09-22T16:00:00+00:00",
    "ends_at": "2026-10-22T16:00:00+00:00",
    "clears": ["five_hour", "seven_day", "seven_day_overage_included"],
    "paused": false,
    "usable_now": true
  }]
}

Expected output. A new usage.claudeResetCredits in the same shape as codexResetCredits:

"claudeResetCredits": {
  "credits": [{
    "id": "<grant id>",
    "title": "<label>",
    "status": "available",
    "resets_left": 1,
    "starts_at": "2026-09-22T16:00:00Z",
    "expires_at": "2026-10-22T16:00:00Z",
    "clears": ["five_hour", "seven_day", "seven_day_overage_included"],
    "usable_now": true
  }],
  "availableCount": 1,
  "updatedAt": "..."
}

• A grant is available when it isn't paused, resets_left > 0, and now is between starts_at and ends_at.
• availableCount adds up resets_left across available grants. It doesn't count grants.
• If the account isn't eligible or the block is missing, leave the field out.