claude-usage-limits 1.9.2 → 1.11.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.9.2",
+  "version": "1.11.2",
   "description": "Puts your remaining Claude Code usage limit into Claude's context before every prompt, so it opens with what fits in the budget instead of starting work that gets cut off. Reports headroom as turns rather than percentages, prices a job before you start it, and detects your plan tier.",
   "author": {
     "name": "Ridelink",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "usage-limits",
-  "version": "1.9.2",
+  "version": "1.11.2",
   "description": "Reports how much of your Codex usage limit is left as turns of work rather than a percentage, prices a job before you start it, and counts the other agents sharing the same budget.",
   "author": {
     "name": "Ridelink",

package/README.md

@@ -39,9 +39,10 @@ you just asked for is going to finish, and answering that needs the request and
 the budget in the same place. That place is the model's context, which is where
 this puts them.
 
-So: if you want to watch your usage, install a status line. This ships one too.
-If you want the thing spending the budget to know it is spending the budget,
-that is what this is for.
+So: if you want to watch your usage, install a status line. This ships one
+too, and a live panel that sits beside the chat, both drawn in Claude Code's
+own colours from Claude Code's own numbers. If you want the thing spending the
+budget to know it is spending the budget, that is what this is for.
 
 ## What it prints
 
@@ -275,30 +276,120 @@ trusted publishing over OIDC, so there is no publish token stored in the repo
 or in CI. `npm version` also syncs the version in the plugin manifest, so the
 marketplace and the npm package never disagree about which release is current.
 
-## Status line
+## Right next to the chat
 
-For a permanent readout instead of asking, point Claude Code's status line at
-the same script. In `settings.json`:
+```
+npx claude-usage-limits panel --open
+```
 
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "node ~/.claude/skills/usage-limits/scripts/usage.js --status"
-  }
-}
+That opens a narrow pane to the right of the one Claude Code is running in
+(Windows Terminal, tmux, WezTerm, kitty, zellij and iTerm2 are all understood)
+and draws the limits in it, live:
+
+```
+✻ Claude usage
+Fable 5.1 · xhigh · working
+
+Current session
+███████░░░░░░░░░░░░░░░░░░░░░ 24%
+resets in 4h 12m at 6:40 PM
+
+Current week (all models)
+█░░░░░░░░░░░░░░░░░░░░░░░░░░░ 4%
+resets in 1d 5h at Sun 7:00 PM
+
+Current week (Fable)
+█░░░░░░░░░░░░░░░░░░░░░░░░░░░ 3%
+resets in 1d 5h at Sun 7:00 PM
+
+Sessions · 1 working, 1 idle
+✳ Fable 5.1  usage-limits  working
+· Opus 5  ridelink  idle 4m ago
+
+live, updated 12s ago
+q quit · r refresh
 ```
 
-It prints one line and prefixes `LOW` once a window passes 90 percent:
+Four things about it are deliberate.
+
+**It is drawn the way Claude Code draws things.** The colours are Claude
+Code's own theme, read out of the CLI rather than approximated: the bar is the
+one `/usage` paints, the title is the Claude orange, the spinner is Claude's
+spinner with Claude's frames. A bar turns yellow at 80 percent and red at 90,
+each window judged on its own. While Claude is working the title shimmers and
+the spinner turns; while it waits, they stop. Under ultracode both go rainbow,
+which is what Claude Code does with its max effort tag.
+
+**The numbers are the ones Claude Code uses.** Every reading is the same GET
+that `/usage` makes, with the login Claude Code already holds, plus the
+rate-limit headers on Claude's own API responses whenever the status line
+below is installed. Whichever is newer wins, and the footer says how old it
+is. The week for one model (the Fable line above) only appears while that
+model is the one running, because it cannot stop work on any other; when the
+model cannot be told at all, nothing is hidden on a guess. The
+reading is kept in `usage-limits-live.json`, and the report, the hooks and the
+status line all prefer it whenever it is newer than Claude Code's own cache,
+which can sit hours behind.
+
+**It keeps drawing when things go wrong.** Offline, it shows the last reading
+and says how old it is, and tries again at a widening interval. Signed out, it
+says so in red and keeps checking, because Claude Code refreshes the login on
+its own next call. Told to slow down by the endpoint, it waits exactly as long
+as it was told. Too narrow a pane loses the breathing room, then the footer,
+never the bars. Nothing in it refreshes or rotates the token, and the token is
+never written anywhere by this plugin.
+
+**It knows about the other Claudes.** Two windows share one limit, so the
+panel lists every session this machine has heard from in the last quarter of
+an hour: what it runs, where, and whether it is working right now, each with
+its own spinner. The hooks are what say so (a prompt marks a session working,
+every tool call keeps it so, the Stop hook marks it idle), so the list is live
+without anyone polling anything. The status line adds `+1 working` when
+another session is spending.
+
+`panel` alone runs it in the current pane, `--once` prints one frame, `--json`
+prints the fields, `--no-fetch` (or `USAGE_LIMITS_FETCH=off`) keeps it
+entirely offline on the reading already on disk, and `--poll N` sets the
+seconds between readings (30 while Claude works and 120 while it waits
+otherwise). Installed as a plugin, `/usage-limits:panel` opens it from inside
+the chat.
+
+Not on the desktop app or claude.ai, which show the limits themselves. This is
+for the terminal and the VS Code extension, where the only way to see them is
+to ask with `/usage`.
+
+## Status line
+
+The same bars, one line under the prompt:
+
+```
+✻ Fable 5.1 · xhigh  session ████░░░░░░ 42%  week █░░░░░░░░░ 7%  fable █░░░░░░░░░ 3%  +1 working
+```
 
 ```
-5h 62% 1h 40m  wk 75% 2d 4h
+npx claude-usage-limits statusline on
+npx claude-usage-limits statusline off
 ```
 
-`--status` reads only the cached percentages and never opens a transcript, so
-it runs in about a tenth of a second and is safe on every redraw. Use the full
-path rather than `~` if your shell does not expand it, and point it at the
-plugin copy instead if that is how you installed it.
+`on` points Claude Code's `statusLine` setting at a small launcher in the
+config directory that finds wherever the plugin is currently installed, so a
+plugin update does not leave the status line pointing at a folder that has
+gone. A status line that was already there is kept and printed above ours;
+`--no-chain` replaces it instead, and `off` restores exactly what was there,
+including nothing. `--refresh N` re-runs it every N seconds as well as on every
+change, which keeps the spinner turning between responses at the cost of a
+Node process every N seconds. The change applies to new sessions.
+
+The line is also where the panel learns what Claude is doing. Claude Code
+hands the status line the model in use, the effort level, and the rate limits
+from its own response headers, and the line records them for the panel, which
+never sees that JSON. It reads no transcripts and makes no network calls, so it
+costs about a tenth of a second on every redraw. It shrinks to fit narrow
+windows, honours `NO_COLOR` and Claude Code's `prefersReducedMotion`, and
+prints nothing rather than an error if anything goes wrong.
+
+The older one-line form is still there as `usage.js --status`, which prints
+`5h 62% 1h 40m  wk 75% 2d 4h` and prefixes `LOW` past 90 percent.
 
 ## It tells you where you stand, every time
 
@@ -331,6 +422,15 @@ explaining is pace: two days into a week you should be near 29 percent spent, so
 60 percent means you will not last the week, and that is worth hearing at 60
 rather than at 85.
 
+The percentages behind the line are kept fresh too. If the reading on disk is
+older than three minutes when a prompt goes in, the hook first takes the same
+reading Claude Code takes for `/usage`, and the mid-turn pulse does the same
+every two minutes through a long turn. That is what stops a burst of parallel
+agents from emptying a window between two readings: eight of them once spent
+half a window in five minutes while the line, seventeen minutes old, still
+said 42 percent. Offline that is one quick failure and then a widening
+backoff, never a wait on every prompt.
+
 One limit worth knowing: the hook fires when a prompt is submitted, so a
 message sent while Claude is already working does not refresh it. Claude Code
 delivers those into the running turn without re-running hooks, which no plugin
@@ -353,6 +453,14 @@ minute, so it costs about 400ms cold and 120ms warm.
 | `USAGE_LIMITS_PULSE` | on | `off` silences the mid-turn line; `always` prints it even when there is room. |
 | `USAGE_LIMITS_PULSE_SECONDS` | 120 | How often the mid-turn line can fire. |
 | `USAGE_LIMITS_TALLY` | on | Set to `off` to turn off the after-reply tally, the closing line and the session history. |
+| `USAGE_LIMITS_FETCH` | on | `off` keeps the panel and the hooks off the network; they show the reading already on disk. |
+| `USAGE_LIMITS_REFRESH` | 180 | Seconds a reading may age before the before-prompt hook takes a fresh one. The mid-turn pulse uses its own interval. |
+| `USAGE_LIMITS_POLL` | 30 / 120 | Seconds between the panel's readings, working / idle. Never under 15. |
+| `USAGE_LIMITS_MOTION` | on | `off` stops the spinner, the shimmer and the rainbow. Claude Code's `prefersReducedMotion` setting does the same. |
+| `USAGE_LIMITS_STATUSLINE` | on | `off` blanks the status line while still recording the feed the panel reads. |
+| `USAGE_LIMITS_CLOCK` | from settings | `12h` or `24h` for reset times; otherwise follows Claude Code's `timeFormat`. |
+| `USAGE_LIMITS_COLOUR` | detected | `256` or `none` to override colour detection. `NO_COLOR` and `FORCE_COLOR` are honoured. |
+| `USAGE_LIMITS_ASCII` | off | `1` draws the bars and the spinner with plain characters. |
 
 ## What a session cost
 
@@ -514,6 +622,18 @@ codex plugin marketplace add https://github.com/ridelink0/claude-code-usage-limi
 codex plugin add usage-limits@usage-limits
 ```
 
+The panel works under Codex too, GPT-6 Astra included:
+
+```
+npx claude-usage-limits panel --open --host codex
+```
+
+It reads Codex's own meter the way `/status` does, through a short-lived
+`codex app-server`, and draws the same bars under the title `Codex usage`,
+with the model named the way Codex names it. Codex has no status line and no
+hooks, so there is no spinner for a working session and no Sessions list; the
+numbers are the point.
+
 ### One thing is different, and it is worth being straight about
 
 Under Claude Code the budget line arrives on its own, because a plugin can ship
@@ -542,6 +662,27 @@ Two smaller differences. There is no money column: Codex meters a share of an
 allowance and never quotes a price, so the percentages stand alone. And
 `lowpower` is Claude Code only, because it writes Claude's `settings.json`.
 
+## VS Code
+
+The Claude Code extension for VS Code shows the limits only when you ask with
+`/usage`, and it does not render a custom status line. So there is an
+extension of its own in [vscode/](vscode/): the same bars as a view that sits
+directly under the Claude Code chat in the secondary side bar (it contributes
+into the Claude Code extension's own view container, so there is no gap and
+nothing to arrange), a status bar item with the percentages that turns yellow
+and red at the same thresholds, the Sessions list, and the same animations in
+CSS. It carries the plugin's scripts inside it, so it has no dependencies and
+reads the same files and takes the same reading as the terminal panel.
+
+```
+cd vscode && npm run package
+code --install-extension claude-usage-limits-<version>.vsix
+```
+
+The `.vsix` is attached to each GitHub release. It is not on the Marketplace
+yet; that needs a publisher account, and the steps are in
+[vscode/README.md](vscode/README.md).
+
 ## Where it works
 
 Every surface of Claude Code on a machine shares one config directory, so
@@ -550,9 +691,9 @@ this reads all of them and does not care which one you are in:
 | Surface | Works | Notes |
 | --- | --- | --- |
 | Terminal (`claude`) | yes | |
-| VS Code extension | yes | |
+| VS Code extension | yes | The VS Code extension above puts the bars under the chat and in the status bar. |
 | JetBrains extension | yes | |
-| Desktop app | yes | |
+| Desktop app | yes | The budget line and the hooks. The panel, the status line and the VS Code extension are for the terminal and VS Code; the app shows the limits itself. |
 | Headless (`claude -p`) | yes | Scripts run fine, but there are no slash commands, so `lowpower.js` is the only way to change effort. |
 | Cloud and web sessions | partly | Those run on a remote machine with their own config directory. Percentages are per-account and stay correct; the pace is measured from whatever transcripts are local to wherever you run the script. |
 
@@ -600,8 +741,13 @@ Node 18 or newer, and a Claude Code recent enough to write
 `cachedUsageUtilization` into `~/.claude.json`. If the report says it found no
 snapshot, run `/usage` once inside Claude Code and it will be there.
 
-Nothing is uploaded. No API key, token, or credential is read. Everything comes
-from files already on the machine.
+Nothing is uploaded. The report and the status line read only files already on
+the machine. The panel, and the hooks when the reading on disk is older than a
+few minutes, take the same reading Claude Code takes for `/usage`: they read
+the login token Claude Code keeps and send it to Anthropic's usage endpoint,
+nowhere else. The token is never written to disk by this plugin, never
+printed, and never refreshed or rotated. `USAGE_LIMITS_FETCH=off` keeps all of
+it offline, on the reading Claude Code itself last cached.
 
 ## How accurate is it
 
@@ -631,6 +777,24 @@ Good enough to plan with, not a bill. The honest caveats:
 - The account's own list of limits is read as well as the per-window buckets,
   so a per-model weekly such as `weekly (Fable)` shows up as a window of its
   own, priced from that model's calls alone.
+- A per-model weekly only counts against you while you are running that model.
+  One at 88 per cent is not your wall if you are working on Opus: nothing you
+  do moves it. Those windows are still listed, marked `not in use`, but they
+  are never picked as the binding window, never raised as a warning, never a
+  reason a forecast says the job does not fit, and never what puts `LOW` on the
+  status line. Start using that model and they come straight back. Nothing is
+  suppressed unless both sides are recognised: an unknown model in the setting,
+  or a weekly scoped to a model this table has never heard of, is treated as
+  live, because hiding a limit that can stop the work is worse than showing one
+  that cannot.
+- The report also says what the room left buys in turns of each model, priced
+  from that model's own measured cost per turn, against the window its spend
+  lands in. Rows sharing a window are alternatives rather than additions. A
+  model that has only ever run as a subagent gets no projected turn count at
+  all - its errands are not turns - though what delegating to it has cost is
+  still reported. What each model cost is remembered in
+  `usage-limits-models.json`, one entry per family, so a session that opens on
+  a model it has not run this week still knows its price.
 - The turn cost behind "turns of headroom" is a median over at least five
   turns, so one compaction cannot define your pace.
 - What a point of a window costs is learned once from the best sample seen and
@@ -670,15 +834,22 @@ skills/usage-limits/SKILL.md      what the agent reads
 skills/usage-limits/agents/       how Codex lists the skill
 skills/usage-limits/scripts/      usage.js, brief.js, pulse.js, stop.js,
                                   sessionend.js, tally.js, codex.js, host.js,
-                                  lowpower.js, install-codex-hook.js
+                                  lowpower.js, install-codex-hook.js,
+                                  recommend.js, panel.js, feed.js,
+                                  statusline.js, live.js, view.js, bars.js,
+                                  activity.js
 skills/usage-limits/references/   the longer notes
 hooks/hooks.json                  runs brief.js before each prompt, pulse.js
                                   during long turns, stop.js after each reply
                                   and sessionend.js when the session closes
 commands/check.md                 the /usage-limits:check command
 commands/session.md               the /usage-limits:session command
+commands/panel.md                 the /usage-limits:panel command
+commands/statusline.md            the /usage-limits:statusline command
 bin/cli.js                        the npx entry point
 tools/sync-version.js             keeps the manifest version in step
+vscode/                           the VS Code extension; build.js copies the
+                                  scripts into vscode/lib and makes the vsix
 test/                             node --test, no dependencies
 ```
 
@@ -688,7 +859,7 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-308 tests over the pricing, the window arithmetic, plan and credit detection,
+469 tests over the pricing, the window arithmetic, plan and credit detection,
 the status line, the before-prompt line, the mid-turn pulse, the after-reply tally and the session history, job forecasting,
 per-project attribution, the Codex reader and its installer, the CLI,
 packaging, and the settings save/restore.

package/bin/cli.js

@@ -18,6 +18,14 @@ const HELP = `claude-usage-limits - how much agent usage is left, and whether th
   claude-usage-limits --host codex        read Codex's limits instead
   claude-usage-limits --host codex --refresh   ask Codex for a live reading
 
+  claude-usage-limits panel               live bars beside the chat; q quits
+  claude-usage-limits panel --open        open it in a split pane to the right
+  claude-usage-limits panel --once        one frame, for a pipe or a screenshot
+
+  claude-usage-limits statusline status   is the status line installed
+  claude-usage-limits statusline on       bars under the Claude Code prompt
+  claude-usage-limits statusline off      put back what was there
+
   claude-usage-limits lowpower status     show the current effort setting
   claude-usage-limits lowpower on         lower effortLevel, remembering the old value
   claude-usage-limits lowpower on --effort medium --model sonnet
@@ -30,7 +38,9 @@ const HELP = `claude-usage-limits - how much agent usage is left, and whether th
 Reads the usage figures the agent already keeps on disk, plus its own session
 history, to report the remaining headroom as turns of work. Works with Claude
 Code and with Codex; the host is detected, or state it with --host. Nothing is
-uploaded and no credentials are read.
+uploaded. The panel, and the hooks when the reading on disk has aged, take the
+same reading Claude Code takes for /usage, with the login Claude Code already
+holds, and send it nowhere else (USAGE_LIMITS_FETCH=off keeps it all offline).
 
   https://github.com/ridelink0/claude-code-usage-limits
 `;
@@ -58,6 +68,16 @@ function run(argv) {
     return Promise.resolve(installer.main(args.slice(1)));
   }
 
+  if (args[0] === 'panel') {
+    const panel = require('../skills/usage-limits/scripts/panel.js');
+    return Promise.resolve(panel.main(args.slice(1)));
+  }
+
+  if (args[0] === 'statusline') {
+    const statusline = require('../skills/usage-limits/scripts/statusline.js');
+    return Promise.resolve(statusline.main(args.slice(1)));
+  }
+
   const usage = require('../skills/usage-limits/scripts/usage.js');
   return Promise.resolve(usage.main(args));
 }

package/commands/panel.md

@@ -0,0 +1,14 @@
+---
+description: Open the live usage panel in a pane beside this chat
+---
+
+Run `node "${CLAUDE_PLUGIN_ROOT}/skills/usage-limits/scripts/panel.js" --open`.
+
+It opens a narrow pane to the right of this one (Windows Terminal, tmux,
+WezTerm, kitty, zellij or iTerm2) showing the current session, the current
+week, and the week for the model in use when the account caps that model on
+its own, as live bars in Claude's colours. If this terminal cannot be split it
+prints the command to run in a second pane instead; pass that on to me.
+
+Tell me in one line what happened and stop. Do not start other work as part
+of this command.

package/commands/statusline.md

@@ -0,0 +1,15 @@
+---
+description: Put the usage bars under the prompt (on), take them out (off), or say which it is (status)
+---
+
+Run `node "${CLAUDE_PLUGIN_ROOT}/skills/usage-limits/scripts/statusline.js" $ARGUMENTS`.
+With no argument it reports the current state.
+
+It edits the `statusLine` entry in `settings.json` in the Claude config
+directory (`~/.claude`, or `CLAUDE_CONFIG_DIR`) through a
+temporary file, keeps a backup, and `off` restores exactly what was there. A
+status line that was already set is kept and printed above ours. The change
+applies to new Claude Code sessions, not this one.
+
+Read the output back to me in one or two lines and stop. Do not start other
+work as part of this command.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.9.2",
+  "version": "1.11.2",
   "description": "Puts your remaining Claude Code usage limit into Claude's context before every prompt, so it opens with what fits in the budget instead of starting work that gets cut off. Reports headroom as turns rather than percentages, prices a job before you start it, and detects your plan tier.",
   "keywords": [
     "claude",

package/skills/usage-limits/SKILL.md

@@ -110,6 +110,14 @@ from the start of the turn. A message sent while you are already working does
 not fire it again: it arrives without a budget line, and the numbers you are
 holding are now older than they look.
 
+The reading itself is kept fresh: the hook takes the same reading Claude Code
+takes for `/usage` when the one on disk is older than three minutes, and the
+mid-turn pulse does the same every two minutes through a long turn. So the
+figures are as good as `/usage` at those moments. What no hook can do is fire
+between them, and a burst of parallel agents can spend a great deal in the
+gap: eight workflow agents once emptied half a 5-hour window in five minutes.
+Spawn agents knowing that each fresh context re-reads what you already hold.
+
 That matters most when it is the one thing you are about to assert. Re-check
 before saying a job fits, if any of these are true:
 
@@ -202,6 +210,22 @@ when a window that is not binding sits near its wall, say so and weigh it. The
 hook flags those. Running the weekly out to save a few turns of the 5-hour
 window is a bad trade even though the 5-hour is what runs out first.
 
+The exception is a weekly that caps one model. `weekly (Fable)` at 88 per cent
+is not your wall while you are working on Opus - nothing you do moves it, and
+doing less work will not un-spend it. The report marks those `not in use` and
+the hook leaves them out of what it asks you to weigh. Do not weigh them back
+in. They matter again the moment you switch to that model, and that is when
+they come back.
+
+That cuts both ways, and the second half is the useful one: when the window
+that binds is a per-model weekly, the same work on another model draws on a
+different window. The report's **Model headroom** table says what the room left
+buys in turns of each model, priced from what that model has really cost here.
+Moving mechanical bulk onto a model with room is not doing less work - it is
+the same work against a wall that is further away, which is the one economy
+worth making. A model with no turn count in that table has only ever run as a
+subagent; its errands are not turns, so there is nothing to project from.
+
 One thing to get right: **quote the binding window, not the roomiest one.**
 Two windows run at once and they are rarely in the same place. The turns of
 headroom and the reset time belong to whichever runs out first. Putting the
@@ -419,6 +443,13 @@ Do not run the report on every prompt. Once at the start of a long piece of
 work, and again if the job grows or something starts looping. The report costs
 a turn, which is the thing it is trying to save.
 
+The panel (`scripts/panel.js --open`, or `/usage-limits:panel`) and the status
+line (`scripts/statusline.js on`) are for the person watching, not for you.
+Nothing in them changes what you should do, and they draw from the same
+reading the budget line already gave you, so do not open or install them
+unless asked. When asked, run the command, say in one line what it did, and
+stop.
+
 ## Files
 
 | Path | What it is |
@@ -435,4 +466,9 @@ a turn, which is the thing it is trying to save.
 | `scripts/lowpower.js` | `status`, `on`, `off`. Restores what it replaced. Claude Code only. |
 | `scripts/recommend.js` | The chooser behind `usage.js --recommend`: posture, then the effort and model commands for each lever. Not meant to be called by hand. |
 | `references/tactics.md` | Every lever that lowers cost, and why it works. |
+| `scripts/panel.js` | The live panel beside the chat: `--open` puts it in a split pane to the right, `--once` prints one frame, `--json` the fields. For the person, not for you; open it only when asked. |
+| `scripts/statusline.js` | `status`, `on`, `off`. Puts the bars under the prompt and restores what was there. |
+| `scripts/feed.js` | The status line command Claude Code runs. Not meant to be called by hand. |
+| `scripts/live.js` | The usage reading itself, taken the way Claude Code takes it for `/usage`, kept in `usage-limits-live.json` where `collect()` prefers it when newer than the cache. |
+| `scripts/view.js`, `scripts/bars.js`, `scripts/activity.js` | The display model, the drawing in Claude's colours, and the working/idle marks the hooks leave for the panel. Not meant to be called by hand. |
 | `references/how-it-works.md` | Where the numbers come from and where they are soft. |

package/skills/usage-limits/references/how-it-works.md

@@ -1,7 +1,10 @@
 # Where the numbers come from
 
-Everything is read from local files. Nothing is sent anywhere, and no API key
-or token is read.
+Everything is read from local files, with one exception: the panel, and the
+hooks when the reading on disk is older than a few minutes, take the same
+reading Claude Code takes for `/usage`, which sends the login token to
+Anthropic's usage endpoint and nowhere else (the last section of this file).
+Nothing else is sent anywhere, and `USAGE_LIMITS_FETCH=off` stops that too.
 
 ## Sources
 
@@ -36,6 +39,68 @@ window of its own, labelled `weekly (Fable)` and priced from that model's
 calls alone; `is_active` breaks ties in the binding choice; and a bucket that
 quotes `limit_dollars` is priced from that directly instead of being calibrated.
 
+A per-model weekly caps one model family and nothing else, so it can only stop
+work that uses that family. Which families are in use is taken from the model
+in `settings.json` (and `ANTHROPIC_MODEL`), plus every model this session has
+actually run, subagents included. Another session's models are not counted:
+what another window is burning is not this one's constraint. A setting that
+names a strategy rather than a model resolves to every model it runs, so
+`opusplan` counts as both Opus and Sonnet.
+
+A window for a family that is not in use is still listed everywhere it was
+listed before - it is real, and switching to that model would make it bite -
+but it is never chosen as the binding window, never raised as a warning, never
+a reason a forecast says the job does not fit, and never what puts `LOW` on the
+status line. It is marked `not in use` in the report and "(not this session's
+model)" in the before-prompt line.
+
+Nothing is suppressed unless both sides are recognised. If the model in use
+cannot be worked out, or the weekly is scoped to a model this table has never
+heard of, the window is treated as live. Hiding a limit that can stop the work
+is the one failure worse than over-reporting one.
+
+The one-line `--status` readout is the exception worth knowing about: it reads
+no transcripts by design, so the only thing it can know about the running
+model is the setting. It therefore shows every per-model weekly and simply
+does not let an idle one raise `LOW`. The status line proper (`feed.js`) is
+told the model by Claude Code itself and needs no such caution.
+
+## Model headroom
+
+How much room is left is half the question; what that room buys is the other
+half, and the answer differs by model. The snapshot cannot say: it has no model
+dimension at all. Every transcript line carries its model, so each family is
+joined to the window its spend lands in - its own weekly where the account
+gives it one, the shared weekly otherwise - and priced from its own turns.
+
+Rows that share a window are alternatives, not additions. They describe the
+same remaining room spent on different models.
+
+No turn count is projected for a model that has never taken a turn of its own.
+A family that has only ever run as a subagent has errands to price, not turns:
+114 Sonnet calls on one machine averaged under two cents because they were
+one-shot lookups, and dividing the remaining budget by that promised twenty-two
+thousand Sonnet turns. The row still reports what delegating to that model has
+cost, because that is measured; it does not project from it.
+
+What a turn of each model cost is kept in `usage-limits-models.json` in the
+config directory, one entry per family so it cannot grow, stamped with the plan
+and read back through the same guard as the window calibration. It exists so a
+session that opens on a model it has not run this week still knows what that
+model costs. It is deliberately not written into `usage-limits-calibration.json`:
+that file means one thing, the plan's blended price of a point, and three
+callers read it on that basis.
+
+There is no per-turn log. Every model figure comes from the transcripts, which
+already hold it; an append-only ledger would grow without bound and record
+nothing new.
+
+Nothing here claims the meter weights a dollar of one model differently from a
+dollar of another. No published or observed source shows that, and the two
+prices per point this plugin learns - one for a shared weekly, one for a scoped
+one - are percentages of two differently sized allowances, which says nothing
+about weighting either way.
+
 The plan name comes from `oauthAccount.organizationType` in the same file.
 Current effort and model come from `settings.json` in the config directory.
 
@@ -206,3 +271,51 @@ be wrong about a budget.
 
 Rows priced this way are marked with an asterisk in the report, so an assumed
 rate never quietly passes for a published one.
+
+## The live reading, and which reading wins
+
+Claude Code takes its own `/usage` figures with one GET to
+`https://api.anthropic.com/api/oauth/usage`, sending the login token it holds
+as a bearer token with the `anthropic-beta: oauth-2025-04-20` header and a
+five second timeout. `scripts/live.js` makes exactly that call, reads the
+token from `.credentials.json` inside the config directory (or the
+`Claude Code-credentials` keychain entry on macOS), and writes the answer to
+`usage-limits-live.json` with the account it belongs to. The token is used for
+that one request and nothing else: never written, never printed, never
+refreshed. If it has expired the endpoint says 401, the panel says "sign in to
+Claude Code again", and Claude Code fixes it on its own next call.
+
+`collect()` then has two snapshots of the same account, Claude Code's
+`cachedUsageUtilization` and the live file, and takes whichever is newer. The
+choice is `preferLive()`: the live file loses when it is older, when it names a
+different account, or when its timestamp is more than a minute in the future.
+`snapshotSource` in the report says which one was used. Everything downstream -
+the budget line, the pulse, the status line, the forecast, the recommendation -
+goes through `collect()`, so they all see the newer reading.
+
+The status line has a third source that is fresher than either: Claude Code
+hands it `rate_limits` built from the `anthropic-ratelimit-unified-*` headers
+on its own API responses, for the session and the shared week. `feed.js`
+records those per session in `usage-limits-feed.json`, along with the model
+and effort in use, and `view.js` takes the newest of headers, live reading and
+cache for each window. The per-model weeks are only in the endpoint's answer,
+so they come from the live file or the cache.
+
+Which per-model week to show is decided by the model in use, never by the
+account's `is_active` flag: that flag marks the limit currently binding, not
+whether the model is running. The status line's `model.id` is certain, the
+`model` setting is the fallback, and with neither nothing is hidden.
+
+Whether Claude is working comes from the hooks: the prompt hook marks the
+session working (and whether the prompt said `ultracode`), every tool call
+keeps it so, and the Stop and SessionEnd hooks mark it idle. Marks live in
+`usage-limits-activity.json`, one per session, and a session silent for fifteen
+minutes counts as idle whatever it last said, because a crash never sends
+Stop.
+
+The sessions list joins those marks with the status line feed (model, effort,
+directory), the Stop hook's tally (project, cost, turns) and the prompt hook's
+cache (when it last prompted), one row per session id, in
+`activity.combine()`. A session is listed if any of them saw it in the last
+fifteen minutes and is working only if its own mark says so and is fresh, so
+the header, the list and the `+N working` on the status line always agree.