Skip to content

✨ gauge: show Claude usage credits (on/off, spent of monthly cap) - #19281

Open
Danathar wants to merge 1 commit into
hivecommons:v5from
Danathar:feat/claude-usage-credits-gauge
Open

Danathar wants to merge 1 commit into
hivecommons:v5from
Danathar:feat/claude-usage-credits-gauge

Conversation

@Danathar

Copy link
Copy Markdown
Contributor

The Overview usage gauge now shows Claude's usage credits (extra usage) under the Claude dials: whether they're on, and how much of the monthly cap is spent. Andy asked 11-19 for provider budget credits on the gauge, "just claude at least". This targets v5; Andy forward-ports it to v6.

What you see

One line under the Claude dials:

Claude reports Line
On, $0.00 of a $350.00 cap Usage credits: on · $0.00 of $350.00 used this month
Off Usage credits: off
Monthly cap spent Usage credits: limit reached · $350.00 of $350.00 … (amber)
Nothing (older response) no line

It's display only. Nothing is turned on, bought or redeemed.

Where the data comes from

It comes from the same GET /api/oauth/usage response the Claude prober already reads; there's no new call. On a live read (11-19) that response carries, next to limits:

  • a spend object: enabled, plus used/limit as {amount_minor, currency, exponent}
  • an extra_usage object: is_enabled, monthly_limit/used_credits in cents, decimal_places, spend_limit_reached

The reading keeps this as Headroom.ExtraUsage. It prefers spend and falls back to extra_usage. Every field is tri-state: nil means Claude didn't say, and it's never shown as 0 or off. Both objects are decoded separately from limits, so an unexpected shape there can't fail the plan reading. PaidCreditsAvailable follows the enabled flag. /api/providers/headroom serializes it as extra_usage (Headroom's custom MarshalJSON lists its fields, so it's added there).

Not shown, because the endpoint doesn't expose them: the purchased credit balance (spend.balance is null, while claude.ai shows the purchased amount) and banked limit resets (no field). Getting those would mean claude.ai's own web API, which is out of scope.

MCP parity: v5 has no admin MCP, so there's no MCP read to extend here. The v6 forward port should add extra_usage to v6's provider-headroom MCP read alongside the dashboard.

Tests

  • rotation_claude_extra_usage_test.go: a new fixture shaped like the live response (testdata/claude_oauth_usage_extra_usage.json; provenance in testdata/README.md) goes through the real HTTP path. Also covered: disabled, limit reached, absent/null/empty/wrong-typed objects (nil, and no extra_usage in the JSON), and the extra_usage-only fallback, including a malformed spend. The plan windows are unchanged in every case.
  • subscription_gauge.test.js: the line for on, off, limit reached, not reported (hidden) and a non-USD currency. All 27 pass locally under node --test.
  • subscription_gauge_overview_test.go: the render wiring.
  • Docs: dashboard.md (usage gauge) and api-reference/cost-tokens-telemetry.md. Changelog: changelog.d/added-claude-usage-credits-gauge.md.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1

The Claude prober's /api/oauth/usage response carries Claude's extra usage
(usage credits) next to the plan windows: a `spend` object (enabled, used and
limit in minor units with an exponent) and an `extra_usage` object (the same
in cents, plus spend_limit_reached). The reading now keeps it as
Headroom.ExtraUsage, tri-state throughout (nil = Claude did not say, never 0
or off), preferring spend and falling back to extra_usage. Both are decoded
apart from the limits, so an odd shape there never fails the reading.
PaidCreditsAvailable follows the enabled flag.

/api/providers/headroom serializes it as extra_usage, and the Overview gauge
shows one line under the Claude dials: "Usage credits: on · $0.00 of $350.00
used this month", "off", or "limit reached" in amber; hidden when unknown.
Display only. The endpoint reports no purchased balance (spend.balance is
null) and no banked limit resets, so those are left out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BQYnPGFJx81c8JXR3o1sg1
Signed-off-by: Danathar <6772335+Danathar@users.noreply.github.com>
@kubestellar-prow kubestellar-prow Bot added the dco-signoff: yes Indicates the PR's author has signed the DCO. label Nov 19, 2026
@kubestellar-prow

Copy link
Copy Markdown
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign hanthor for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details Needs approval from an approver in each of these files:

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

@kubestellar-prow kubestellar-prow Bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Nov 19, 2026
@github-actions

Copy link
Copy Markdown
Contributor

UI render evidence

Render evidence captured.

Built from 81cb7ea4f2cb.
Screenshots: download the artifact (sign-in to GitHub required).
Run: https://github.com/hivecommons/hive/actions/runs/44573035795

Page Section Viewport Theme File Size
hive overview desktop light hive-overview-desktop-light.png 351 KB
hive overview-section desktop light hive-overview-section-desktop-light.png 295 KB
hive overview desktop dark hive-overview-desktop-dark.png 326 KB
hive overview-section desktop dark hive-overview-section-desktop-dark.png 272 KB
hive overview phone light hive-overview-phone-light.png 506 KB
hive overview-section phone light hive-overview-section-phone-light.png 357 KB
hive overview phone dark hive-overview-phone-dark.png 503 KB
hive overview-section phone dark hive-overview-section-phone-dark.png 353 KB

These are fixture renders, not live data: the page was built from the PR head and filled with synthetic data from src/scripts/fixtures/render-evidence/. They show layout and theming, not how real hives behave. How to read them: src/docs/ui-render-evidence.md.

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR Title Relation Files
#19206 ✨ ask: hive panel and rollout verification for optional Ask AI help same files src/docs/api-reference/cost-tokens-telemetry.md
src/pkg/dashboard/static/index.html
#19204 ✨ ask: hive backend and hub relay for optional Ask AI help same files src/docs/api-reference/cost-tokens-telemetry.md
src/pkg/dashboard/static/index.html
#19265 🐛 Name how a sign-off ask was answered on the tracker Review track same files src/pkg/dashboard/static/index.html

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

dco-signoff: yes Indicates the PR's author has signed the DCO. size/L Denotes a PR that changes 100-499 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant