Feature: Claude usage source via minimal inference call reading anthropic-ratelimit-unified-* headers (multi-account with setup-tokens / user:inference)

[HendrikRidder]

Summary

Add a Claude usage source that reads live 5h/weekly limits from the anthropic-ratelimit-unified-* response headers of a minimal POST /v1/messages call. This works with long-lived claude setup-token credentials (scope user:inference) and would enable multiple persistent Claude accounts in the menu bar without browser cookies — a concrete mechanism for #1756 / #1843 / #1268.

Problem

For people running several Claude subscription accounts via a multi-account switcher (e.g. claude-switch, which mints one ~1‑year claude setup-token per account), CodexBar currently has no clean way to show all of them live at once:

• OAuth API (GET /api/oauth/usage) requires scope user:profile. setup-tokens are user:inference only → 403 (measured). A full /login token has user:profile, but its refresh token rotates and doesn't stay valid — which is exactly why these users switched to setup-tokens.
• Web (cookies): a sessionKey is revoked on logout, so switching accounts in one browser kills the previously-harvested account's data.
• CLI (PTY): single account.

Net result: no durable way to show N long-lived Claude accounts (cf. #1756, #1843, #1268; and token-loss reports like #1823).

Discovery (measured on CodexBar 0.37.2 / macOS)

A minimal inference call with a user:inference setup-token returns HTTP 200 and carries the same unified limits in the response headers:

POST https://api.anthropic.com/v1/messages
authorization: Bearer sk-ant-oat01-…            # a `claude setup-token`, scope user:inference
anthropic-version: 2023-06-01
anthropic-beta: oauth-2025-04-20
content-type: application/json

{"model":"claude-haiku-4-5-20251001","max_tokens":1,"messages":[{"role":"user","content":"."}]}

Response headers:

anthropic-ratelimit-unified-5h-utilization: 0.01      # fraction 0..1
anthropic-ratelimit-unified-5h-reset: 1783180800      # unix seconds
anthropic-ratelimit-unified-7d-utilization: 0.63
anthropic-ratelimit-unified-7d-reset: 1783713600
anthropic-ratelimit-unified-5h-status: allowed
anthropic-ratelimit-unified-representative-claim: five_hour

Notes:

• GET /api/oauth/usage with the same token returns 403 (user:profile required) — the dedicated usage endpoint is unavailable, but the headers carry the equivalent 5h/weekly data.
• POST /v1/messages/count_tokens does not include these headers, so it must be a real (max_tokens:1) messages call. Cost ≈ 1 output token per poll.
• Verified across 4 distinct subscription accounts, each via its own setup-token, all returning correct distinct utilization values.

Proposed feature

For a Claude tokenAccount whose token is an sk-ant-oat… with only user:inference (or as an automatic fallback when /api/oauth/usage returns 403), obtain quota by issuing one tiny inference call and mapping headers:

• unified-5h-utilization / -reset → session (5h) window
• unified-7d-utilization / -reset → weekly window

This lets tokenAccounts backed by setup-tokens show live per-account quota without browser cookies (no logout fragility) and without user:profile — i.e. genuine multi-account overview with durable ~1‑year tokens.

Why it's attractive

• A concrete, durable mechanism for the multi-account requests (Support multiple Claude accounts OR support account swapping with claude-swap #1756, Feature request: Support multiple accounts or instances of the same provider #1843, Allow multiple account in the status bar for same provider. #1268).
• Sidesteps sessionKey logout/expiry and OAuth-refresh fragility (Claude constantly looses token for access #1823 and Claude session repeatedly shows "Unauthorized. Your Claude session may have expired." — both Web and OAuth paths lack working refresh #1287-class issues).
• Minimal cost (~1 token per poll; can be gated behind a refresh interval and used only when OAuth/web are unavailable).

Caveats / open questions

• The model id must be a currently-available model → keep a small fallback list.
• The headers are the subscription unified limits (utilization 0..1). Model-specific weekly (Sonnet/Opus) and the "Daily Routines" window may not be present in the headers — those would still require the usage endpoint / web source.
• Should be opt-in / gated so normal accounts keep using OAuth/web as today.

Happy to provide more header captures, and I can attempt a PR if this direction is welcome. Thanks for CodexBar — it's genuinely great.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed July 29, 2026, 10:52 PM ET / July 30, 2026, 02:52 UTC.

Summary
Keep open for maintainer product direction. This is a concrete, maintainer-researched Claude credential/usage-source proposal, but it adds an opt-in inference-polling mode and persistent multi-account implications rather than repairing an established contract; no evidence here shows that current main has already adopted it.

Reproducibility: not applicable. as a bug reproduction: the issue proposes a new usage source. The reporter and repository owner provide concrete feasibility observations, but they do not establish a failing current-main behavior that must be repaired.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Include the exact command, prompt, or workflow that triggered it.
• Add expected vs actual behavior.

Maintainer decision needed

Question	Recommendation
Should CodexBar support an opt-in Claude setup-token inference probe as a durable quota source, accepting a small real inference request per refresh and undocumented unified headers?	Sponsor an opt-in quota source: Accept the constrained source with explicit polling, model fallback, header-fixture tests, and unified-window-only presentation.

Why: The feasibility mechanism is specific, but choosing whether CodexBar should make authenticated inference calls solely for quota display—and whether it should support durable multi-account token configuration—is an enduring provider and UX policy choice.

Next step
A maintainer must first choose the accepted Claude inference-polling and multi-account support boundary; this is not a safe autonomous repair.

Review details

Best possible solution:

If sponsored, add a narrowly scoped, opt-in Claude setup-token usage source with a small maintained model fallback list, captured-header parser fixtures, explicit unified 5-hour/weekly labeling, and no cross-provider identity or billing-data mixing; consider local audit history only as a separately designed follow-up.

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

Not applicable as a bug reproduction: the issue proposes a new usage source. The reporter and repository owner provide concrete feasibility observations, but they do not establish a failing current-main behavior that must be repaired.

Is this the best way to solve the issue?

Unclear pending maintainer direction. The owner’s stated guardrails make the header-based approach plausible, but only an explicit decision can establish whether authenticated inference polling belongs in CodexBar’s supported Claude-provider boundary.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The anthropic-ratelimit-unified-* headers are undocumented, so their availability, field semantics, and model compatibility can change without notice.
• Each refresh is a real inference request against a durable credential; the feature needs an explicit opt-in, bounded refresh behavior, clear failure handling, and honest unified-window labeling.
• The later request for persisted billing-reconciliation samples broadens the feature into local audit storage and should remain separate from the initial quota-display decision.

Codex review notes: model internal, reasoning high; reviewed against 8ef86077e70a.

Label changes

Label changes:

• remove clawsweeper:fix-shape-clear: Current issue advisory state no longer selects this label.

Label justifications:

• P3: This is a valuable but optional provider enhancement with no established broken-behavior contract.
• impact:auth-provider: The request concerns Claude credential scopes, token-account support, and quota-source routing.

Evidence reviewed

What I checked:

• Maintainer feasibility direction: The repository owner described this as the strongest prior art in the current batch and documented the required boundaries: opt-in polling, a fallback model list, explicit unified 5h/7d labeling, and captured-header fixtures.
• Current item remains a product decision: The proposal introduces a new provider behavior for inference-scoped setup tokens, creates a real periodic inference request, and explicitly asks whether that direction is welcome; existing labels also retain maintainer and product-decision review.
• Related requests are broader, not canonical replacements: The open multi-account requests at Allow multiple account in the status bar for same provider. #1268 and Feature request: Support multiple accounts or instances of the same provider #1843 overlap on the user goal, but neither owns this specific setup-token header-polling design.
• Repository policy applied: The repository AGENTS.md requires provider data to remain siloed, discourages unrequested live account/keychain probing, and directs provider/parser work toward focused fixtures and CLI tests; those constraints support a deliberate design decision before implementation. (AGENTS.md:1, 8ef86077e70a)

Likely related people:

• steipete: The owner added the feasibility assessment, defined the implementation guardrails, and applied the help-wanted label to this proposal. (role: product-direction owner and recent Claude-area reviewer; confidence: high)

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]

Feasibility research update: medium, strongest prior art of the current batch.

The anthropic-ratelimit-unified-* headers are undocumented (the official rate-limits page documents only the requests/tokens families), but they are real and widely relied upon: roughly 20 open-source projects parse them, including Claude-Code-Usage-Monitor, ccflare, and xbar/VS Code status plugins. Cost of the minimal probe (haiku, max_tokens 1) is about 10 input + 1 output tokens per poll; with a setup-token it draws plan quota, not dollars, so even 5-minute polling is noise. The multi-account setup-token mechanics check out (sk-ant-oat01, user:inference scope, roughly 1-year validity).

If someone picks this up: opt-in only (every poll is a real inference request), fallback model list (model IDs rot), honest labeling that granularity is unified 5h/7d only, and tests against captured header fixtures. Marked help wanted.

[COOLak]

A new operational reason to preserve this source—not just display it—is post-incident billing reconciliation.

Anthropic's July 17 incident acknowledged that users were erroneously routed to usage credits, while multiple public reports showed substantial included-plan headroom. In one documented case, six July 17 invoices totaled $599.35 and Anthropic later selected only a 30-minute correction window. Public record: anthropics/claude-code#81703

If the anthropic-ratelimit-unified-* source is accepted, could CodexBar also persist a privacy-safe timestamped sample whenever utilization/status changes materially?

Useful fields would be:

• captured time and provider reset timestamps;
• 5h/7d utilization and status;
• credential/account alias (local pseudonym only);
• source/provenance and stale/fresh state;
• raw header hash or redacted raw-header fixture;
• previous/current values that triggered the sample.

That would let a user prove what the provider reported immediately before and during an unexpected paid-credit transition. It should remain explicitly separate from CodexBar's local token-cost estimate: a calculated cost is not evidence that Anthropic actually billed it.

This is not a claim that CodexBar caused or can fix provider billing. It is a request to make the proposed authoritative quota source useful as a durable audit trail as well as a menu-bar readout.

[steipete]

Closing: harvesting anthropic-ratelimit-* headers requires issuing paid inference calls on the user's account as a side effect of monitoring — a cost and account-safety surface we won't take on, especially post-#2585 where the owner-scoped OAuth path provides usage without it.