[FEATURE] Expose limit-reset grant metadata in `statusline` JSON (read-only)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

I maintain Usage HUD, a local macOS menu-bar usage monitor.

Claude’s Usage settings can show redeemable limit-reset grants, including their type and expiry. However, the documented JSON passed to Claude Code statusline does not expose this grant information.

The existing rate_limits.five_hour and rate_limits.seven_day fields describe usage windows and their scheduled reset times. Those timestamps do not tell a statusline consumer whether the user has a separate reset grant available.

Consequently, a statusline or local dashboard cannot reliably show:

Whether any reset grants remain.

Which usage limit a grant affects.

When an unused grant expires.

Users must check Claude’s Usage settings separately. This is particularly easy to miss when an otherwise available grant has an expiry.

I would like a documented, read-only way to display this information through Claude Code’s existing statusline interface.

Proposed Solution

Please add optional limit-reset grant metadata to the JSON supplied to statusline commands.

The minimum useful information would be:

Remaining reset count.

Reset type or affected usage window.

Expiry timestamp, when applicable.

For example, a proposed addition could look like:

{
"limit_resets": {
"grants": [
{
"affected_windows": ["seven_day"],
"remaining": 1,
"expires_at": 1893456000
}
]
}
}

This is an illustrative schema with synthetic data, not a description of an existing field. Field names and placement are up to the maintainers.

A list would preserve separate types and expiries when multiple grants exist. A single combined count and expiry could otherwise hide important differences between grants.

Please document how consumers should distinguish confirmed absence from unavailable information. For example:

An empty grants list could mean there are no remaining grants.

An omitted limit_resets field could mean the information is unavailable or unsupported.

A documented null or omitted expiry could represent a grant without a known expiry.

When Claude Code obtains updated grant information, subsequent statusline payloads should reflect that update, including grants that have expired or been used.

The feature would be display-only. It would not expose redemption commands, OAuth tokens, account identifiers or other credentials. Redeeming a grant would remain in Anthropic’s own interface.

Alternative Solutions

The current workaround is to check Settings → Usage in Claude web or Desktop.

That remains the appropriate place to redeem a reset, but it requires a separate check just to see whether a grant exists or is nearing expiry.

Scheduled usage-window reset timestamps cannot substitute for grant metadata. We also do not want this feature to depend on undocumented endpoints, private application storage or identifying a third-party tool as an Anthropic client.

A documented statusline field would provide a clear integration point for external tools and local dashboards.

Priority

Medium - Would be very helpful

Feature Category

Interactive mode (TUI)

Use Case Example

• A user works in Claude Code with a statusline or local menu-bar dashboard.

• The user has one unused weekly reset grant.

• The consumer receives its count, affected window and expiry through statusline JSON.

• It displays a compact indicator such as “1 weekly reset available · expires in 5 days.”

• When no grants remain, the indicator disappears. If grant information is unavailable, the consumer avoids presenting that as a confirmed count of zero.

• If the user chooses to redeem a grant, they do so through Claude’s own interface.

Additional Context

Usage HUD does not read grants itself; it only uses the documented statusline interface.

This request is for a supported data export through the existing statusline interface. It is not a request to change grant eligibility, scheduled reset times, subscription limits or authentication policy.

Relevant documentation:

Claude Code statusline fields

What is a limit reset?

Authentication and credential-use policy