Skip to content

Render all usage windows dynamically from the new limits[] API (per-model / Fable, spend) #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
amalakhovsky wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Render all usage windows dynamically from the new limits[] API (per-model / Fable, spend) #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cf5df52
✨ Render all usage windows dynamically from the new limits[] API
amalakhovsky Jul 13, 2026
1255b38
📝 Add AGENTS.md data-source notes and changelog entry
amalakhovsky Jul 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 21 additions & 6 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,11 @@ the LICENSE, `build.sh`, `tools/`) is repo tooling that stays out of the bundle.
- `src/lib/oauth.js` — shared OAuth/API constants (client id, endpoints,
scopes, headers) and text codecs, imported by both `usageClient.js` and
`prefs.js` so the values are defined once. No shell imports.
- `src/lib/usageModel.js` — pure data-shaping: turns the usage payload into the
ordered list of windows the popup renders (`normalizeWindows`, preferring the
self-describing `limits[]` array and falling back to the legacy flat keys) and
the extra-usage money block (`normalizeSpend`). No GI or shell imports, so it
is unit-testable under plain `node` (see `tools/test-usageModel.mjs`).
- `src/stylesheet.css` — `cu-*` classes for the indicator and popup.
- `src/icons/` — panel icon (`claude-spark.svg`) and popup logo
(`octopus.png`).
Expand All @@ -42,17 +47,27 @@ the LICENSE, `build.sh`, `tools/`) is repo tooling that stays out of the bundle.
`dist/<uuid>.shell-extension.zip`. Accepts an optional `-major`/`-minor`/
`-patch` flag that bumps `version-name` (semver) in `metadata.json` and
increments the integer `version` before packing.
- `tools/poll.js` — standalone validator, run from the repo root:
`gjs -m tools/poll.js`.
- `tools/poll.js` — standalone validator that hits the live API and prints the
normalised windows + spend, run from the repo root: `gjs -m tools/poll.js`.
- `tools/test-usageModel.mjs` — pure-`node` unit tests for `usageModel.js`
(no network, no GI): `node tools/test-usageModel.mjs`.

## Data sources

- Tier: `~/.claude/.credentials.json` (`claudeAiOauth.subscriptionType` /
`rateLimitTier`), confirmed via `GET https://api.anthropic.com/api/oauth/profile`.
- Limits: `GET https://api.anthropic.com/api/oauth/usage` returns `five_hour`,
`seven_day`, `seven_day_sonnet` (each `utilization` % + `resets_at`) and
`extra_usage`. Required headers: `Authorization: Bearer <token>`,
`anthropic-beta: oauth-2025-04-20`, `anthropic-version: 2023-06-01`.
- Limits: `GET https://api.anthropic.com/api/oauth/usage`. The current shape is
a self-describing `limits[]` array — each entry has `kind`
(`session`/`weekly_all`/`weekly_scoped`), `group` (`session`/`weekly`),
`percent`, `severity` (`normal`/`warning`/`critical`), `resets_at`,
`is_active`, and an optional `scope.model.display_name` naming a per-model
window (e.g. Fable). Money now comes as a structured `spend` object
(`used`/`limit` as `{amount_minor, currency, exponent}` + `percent` +
`severity`). The older flat keys (`five_hour`, `seven_day`,
`seven_day_<model>` with `utilization` %, plus `extra_usage`) are still parsed
as a fallback in `usageModel.js`. Required headers:
`Authorization: Bearer <token>`, `anthropic-beta: oauth-2025-04-20`,
`anthropic-version: 2023-06-01`.
- Refresh: `POST https://platform.claude.com/v1/oauth/token` with
`grant_type=refresh_token` and the public Claude Code `client_id`.

Expand Down
19 changes: 19 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

## Unreleased

### Added
- Per-model usage windows. Anthropic's usage endpoint now reports its windows in
a self-describing `limits[]` array that includes model-scoped limits (e.g. a
weekly Fable window). The popup renders one meter per reported window
dynamically, so any current or future model the API breaks out shows up
automatically instead of being silently dropped.
- A "Worst active limit" option for *Panel reflects*, so the top-bar gauge can
surface whichever limit is most severe right now — a maxed-out per-model
window reaches the panel even when the 5-hour and 7-day totals are calm.

### Changed
- Gauge colors are now floored at the severity the API reports for each window:
the existing burn-consequence coloring still applies, but a window the API
flags as warning/critical never reads calmer than that.
- The extra-usage line now uses the structured `spend` object (authoritative
amount, limit, percentage, and severity) when present, falling back to the
older `extra_usage` field — and scales it by the API's own decimal places
instead of assuming cents. It tints amber/red with the spend severity.

## 1.1.2 - 2026-07-10

### Changed
Expand Down
Loading