claude-usage-limits 1.25.0 → 1.39.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.25.0",
+  "version": "1.39.1",
   "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.25.0",
+  "version": "1.39.1",
   "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

@@ -19,6 +19,48 @@ opens with the answer instead:
 
 Nobody read a chart to get that. The numbers reached the model, not you.
 
+## What it runs on your machine, and what it never does
+
+Installing this plugin registers six Claude Code hooks, which means Node runs on
+your machine at six moments: `UserPromptSubmit` (the budget line), `PreToolUse`
+(the fan-out line, and the refusal when a cap is set), `PostToolUse` and
+`SubagentStop` (keeping the reading fresh), and `Stop` and `SessionEnd` (the
+session tally). Nothing runs on a timer except a relay wake you armed yourself.
+
+What it reads: your Claude Code transcripts under the config directory, to price
+what has been spent; the account snapshot the host already fetched; and your
+settings files. What it writes: its own files beside those, every one prefixed
+`usage-limits-`, plus the launcher and scheduled task a relay needs while one
+is armed.
+
+**It does read your login.** The live reading is the same call Claude Code
+makes for `/usage`, and making it needs the same OAuth token, so this plugin
+reads it from `.credentials.json` (or, on macOS, the `Claude Code-credentials`
+keychain item) and sends it as a bearer token to
+`https://api.anthropic.com/api/oauth/usage`. That token is never written to a
+file, never logged, and never sent anywhere else: the destination is checked
+against an allowlist first - Anthropic over https, or loopback for the tests -
+because a project settings file can put anything in a hook's environment and
+the override that points at a different endpoint must not become a way to walk
+off with your login. Without a live reading the plugin still works, from the
+snapshot and your transcripts.
+
+Apart from that one call to Anthropic, nothing leaves the machine: no
+telemetry, no upload, no record of your usage kept anywhere else. Everything it
+knows sits in files you can open, and `node bin/cli.js mode off` stops it
+injecting anything at all.
+
+## Do not want any of this?
+
+    node bin/cli.js mode off              nothing injected, ever - including at the wall
+    node bin/cli.js mode off --guard 95   silent, except one short line at 95% used
+    node bin/cli.js statusline off        take the bars out from under the prompt
+
+`off` means off: no budget line, no end-of-reply cost, no panel animation. Most
+people who want quiet actually want the second form - silence until it matters.
+Both apply to new prompts immediately and survive restarts. `mode standard`
+turns it back on.
+
 ## How this differs from a usage dashboard
 
 There are a lot of good tools that read the same local files this does and draw
@@ -333,6 +375,57 @@ What changes while it is armed is what Claude is told at the wall. Instead of
 cut off now costs the wait rather than the work, and that the continuation is a
 prompt to be acted on rather than a summary for a person to read.
 
+**A session that started before an update keeps the old code.** A plugin
+update applies when Claude Code restarts, so two sessions can run two versions
+at once; on 2026-09-20 a session still on 1.34.1 saw the single relay slot that
+version had, took it for occupied, scheduled its own wake by hand, and that
+wake failed the way 1.34.1's always did, while the session on 1.36.0 resumed
+fine. Nothing can upgrade a running session, so since 1.38.0 the budget line
+says so once: the installed version, the running one, and that a relay or cap
+set in that session follows the older rules until it restarts.
+
+**Two things that stopped it in practice, both fixed in 1.36.0.** A fresh
+Claude Code start asks two questions nobody is there to answer at four in the
+morning: whether to trust the folder, and whether bypass permissions is meant.
+On 2026-09-20 the wake opened its window and sat at the trust question until
+morning. Arming now writes both answers into .claude.json for the folder the
+relay will resume in (every spelling of the key, with a backup beside it), the
+wake writes them again right before the launch, and doctor reports when they
+are missing; relay preflight [cwd] does it by hand. And the relay used to hold
+one slot, so a second session arming on the same night was refused or
+displaced the first. Each session now has its own record and its own scheduled
+task; status lists them all, relay cancel takes down this session's, and
+relay cancel --all takes down every one.
+
+**1.37.0 fixed the arm that failed twice on 2026-09-20.** `relay arm` reported
+`Value for '/TR' option cannot be more than 261 character(s)` - schtasks refusing
+the task action, which carried node's path, the plugin cache path, the session
+id and the config directory: 326 characters. That was only the fallback. The
+primary ScheduledTasks route had already been killed at a fixed eight-second
+ceiling while PowerShell was still loading the module (32 seconds on that
+machine), and a timeout has no stderr, so nothing reported it. The task now
+runs a small launcher in the config directory (`relay-task-<id>.cmd`) so the
+action has one fixed length whatever the plugin path; the PowerShell route
+gets a minute from the command line and the hook's own deadline from a hook;
+and a failure names both routes side by side. `relay doctor` also reports
+whether a login is there to resume under. When that login expires is not
+checked: `claude auth status` does not report it and the relay does not read
+`.credentials.json`, so renew `/login` before a relay that fires hours later.
+
+Smaller changes in the same release: the budget line names both account
+readings when Claude Code's cache and the plugin's live reading differ by more
+than five points (`5-hour 20% (the live reading; Claude Code's cache says
+14%)`) rather than showing one number that jumps; its standing instruction is
+said in full once per session and as twelve words after that
+(`USAGE_LIMITS_BRIEF_FULL=1` keeps the full form); one clause is added on the
+prompt right after a prompt-cache miss the user caused - a changed tool list
+or system prompt, read from the status line's `prompt_cache` - and nothing
+otherwise; the mid-turn pulse's tight sentence is throttled to the same ten
+minutes as its fan-out advice; a subagent message written as several content
+blocks is priced by its last block, which carries the real output count
+(measured on 179 agent transcripts: 1,991 of 2,504 such messages ran like
+1, 1, 202); and the headless resume runs with `DISABLE_AUTOUPDATER=1`.
+
 | | |
 | --- | --- |
 | **Off by default** | Scheduling an agent to run while nobody is watching is a decision you make on purpose, not one a plugin makes for you. |
@@ -576,6 +669,7 @@ minute, so it costs about 400ms cold and 120ms warm.
 | Variable | Default | Effect |
 | --- | --- | --- |
 | `USAGE_LIMITS_BRIEF` | on | Set to `off` to turn the before-prompt line off entirely. |
+| `USAGE_LIMITS_BRIEF_FULL` | off | Set to `1` to say the line's standing instruction in full on every prompt. By default it is said in full once per session and as twelve words after that. |
 | `USAGE_LIMITS_NEAR` | 90 | Percent used at which the budget counts as tight. Nothing below it is discouraged. |
 | `USAGE_LIMITS_FEW_TURNS` | 10 | Turns of headroom at or below which the budget counts as tight. |
 | `USAGE_LIMITS_RUNWAY` | 10 | Minutes of runway at the current pace below which the budget counts as tight. |
@@ -1176,7 +1270,7 @@ ever told it the limit was close. The reader now keeps the newest reading of eac
 meter and prefers the one that actually describes a window. Nothing is merged or
 synthesised - the payload returned is one Codex really wrote.
 
-### An old snapshot is a floor, not a reading
+### An old snapshot is an estimate, not a reading
 
 There was already a warning for a reading spent past its own remainder. It could
 never fire for a snapshot taken at the start of a window, because everything
@@ -1188,7 +1282,11 @@ plugin's live reading was rate-limited into backoff, and the correction was
 quietly carrying the entire difference on its own. A correction is a good
 adjustment to a recent snapshot and a bad substitute for an old one, because the
 pricing error compounds with every point it has to bridge. Past fifteen minutes
-the brief now says the figure is a floor and points at `/usage`.
+the brief now says the figure is an estimate that can run high or low and points
+at `/usage`. It is only called a floor when the correction has been refused
+outright and the raw snapshot is all that is shown, since that really is a
+lower bound; a snapshot plus a correction is not, and on 2026-09-20 it ran 13
+to 17 points high.
 
 ### The ceiling
 
@@ -1206,6 +1304,13 @@ It is off until you set a number, it never fires without a reading behind it, an
 the refusal says what to do instead - a denial that only says "over budget" gets
 retried.
 
+It is judged on the fullest window this session can spend into, and the refusal
+names that window. A weekly scoped to one model counts only while that model
+runs - by the setting, or by the model the session's last reply came from, so a
+`/model` switch is seen - and a window whose reset has passed does not count.
+Until 1.39.0 it took the highest number on disk, and an Opus session was refused
+on the Fable weekly with a message calling it "the binding window".
+
 **Why a refusal rather than a sentence.** On Codex the reported figure
 demonstrably does not change behaviour, and the reason is not stubbornness.
 `gpt-6-astra`'s own system prompt, shipped in `models_cache.json`, says: *"Do not

package/commands/relay.md

@@ -23,11 +23,16 @@ The rest:
   when the window opens; a request one second later has been refused before.
 - `mode notify` - raise a notification with the continuation ready to open.
   This is the default and it starts nothing by itself.
-- `mode resume` - at the wake, run the CLI in the project directory and hand
-  the continuation back to the same conversation. Say `permission acceptEdits`
-  (or whichever mode you want) as well: a headless resume does **not** inherit
-  the session's permission mode, so without one it will sit waiting for an
-  approval nobody is there to give.
+- `mode resume` - at the wake, resume the same conversation in a window you can
+  see, with Remote Control on, so it is also on claude.ai/code and the phone;
+  the first prompt points it at the hand-off file. Say `permission acceptEdits`
+  (or whichever mode you want) as well: a resume does **not** inherit the
+  session's permission mode, so without one it will sit waiting for an
+  approval nobody is there to give. `show off` makes it a headless run instead.
+- `voice on|off` - carry how you write in the hand-off, so the resumed session
+  answers in your voice without being reminded. On by default.
+- `bugcheck on|always|off` - the hand-off asks for two bug passes before anything
+  is called done; `always` asks on every prompt as well. On by default.
 - `thinking off|resume|always` - `resume` puts the word ultrathink into the
   prompt the relay delivers. `always` sets `alwaysThinkingEnabled` in your
   settings, backs the file up first, and applies to new sessions.

package/commands/usage-mode.md

@@ -6,6 +6,9 @@ Run `node "${CLAUDE_PLUGIN_ROOT}/skills/usage-limits/scripts/mode.js" $ARGUMENTS
 and report the answer back. Then stop; do not start other work as part of this
 command.
 
+If the user just wants it gone: `off` injects nothing at all, `off --guard 95`
+stays silent until 95 per cent. Say which you ran.
+
 The plugin is not free. It puts a line into your context before every prompt,
 refreshes readings after tool calls, and keeps a status line alive. A mode
 changes two things at once: what the plugin tells you to do, and what it costs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.25.0",
+  "version": "1.39.1",
   "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",
@@ -42,6 +42,7 @@
   "scripts": {
     "test": "node --test",
     "usage": "node bin/cli.js",
-    "version": "node tools/sync-version.js && git add .claude-plugin/plugin.json .codex-plugin/plugin.json"
-  }
+    "version": "node tools/sync-version.js && git add .claude-plugin/plugin.json .codex-plugin/plugin.json vscode/package.json"
+  },
+  "type": "commonjs"
 }

package/skills/usage-limits/SKILL.md

@@ -275,6 +275,16 @@ The user can also ask any time with `/usage-limits:session`, or run
 `--sessions` for the history of recent sessions on this machine.
 
 
+## Turning it off
+
+If the user says they do not want the budget line, the cost line, or the status
+bars, do not argue and do not explain the trade-off unless asked. Run:
+
+    node "$CLAUDE_PLUGIN_ROOT/skills/usage-limits/scripts/mode.js" off
+
+and, for the bars, `statusline off`. `mode off --guard 95` is the middle
+ground: silent until 95 per cent. Say which one you ran and stop.
+
 ## Budget modes
 
 How hard this plugin leans, and what it costs to say it. Four modes, set by the
@@ -620,6 +630,12 @@ which files are mid-change, what must be verified before anything is built on
 it. It is delivered as a prompt, so an instruction beats a summary. If nothing
 is written, the relay falls back to the outstanding todo list, which is worse.
 
+More than one session can be armed at once; each wakes on its own task, and
+cancel takes down only this session's unless --all is given. Arming also
+answers the two start-up questions (folder trust, bypass permissions) in
+.claude.json for the folder it will resume in, so the window does not stop at
+a prompt; doctor says whether they are answered.
+
 **It arms at the end of a reply, not in the middle of one.** Crossing the
 threshold no longer schedules anything by itself: the relay waits for the reply
 to finish, so what it carries is work that reached a boundary rather than a
@@ -646,6 +662,22 @@ machine whose power plan forbids wake timers, a scheduled task this account
 cannot register, no continuation written, no network - and says which would
 bite. Every resumed run's full output is kept: `relay log --run`.
 
+An arm that fails says which route failed and why: the ScheduledTasks route
+and the schtasks fallback are named side by side, since on 2026-09-20 only the
+fallback's refusal was reported and the real failure - PowerShell timing out
+while its module loaded - was never seen. The task runs a small launcher in
+the config directory (`relay-task-<id>.cmd`), so the action fits schtasks
+whatever the plugin path. The doctor also reports whether a login is there to
+resume under; when it expires is not checked, so renew `/login` before a
+relay that fires hours later.
+
+The budget line's standing instruction - open with the fit line, quote the
+binding window, close finished work with the total - is said in full once per
+session and as twelve words after; it is the same instruction. When two
+account readings disagree by more than five points the line names both rather
+than one, and on the prompt right after a prompt-cache miss you caused it says
+so in one clause.
+
 The relay is off unless the user turned it on, and it only arms while there is
 an unfinished todo list or an approved plan to carry. Do not turn it on for
 them, and do not promise behaviour it does not have:
@@ -654,8 +686,13 @@ them, and do not promise behaviour it does not have:
   input to a shell on purpose; the relay uses it only to tell whether somebody
   is at the keyboard, and to show a banner.
 - In `notify` mode — the default — it raises a notification and starts nothing.
-- The resumed run opens in a window you can see. `relay show off` hides it; the
-  output is kept either way.
+- The resumed run is a real interactive session in its own window, with Remote
+  Control on (named `usage-limits relay <project>` on claude.ai/code and the
+  phone), and its first prompt points it at the hand-off file. `relay show off`
+  makes it a headless `claude -p` run instead; the output is kept either way.
+  macOS and Linux open the same window in Terminal (unverified there). A saved
+  continuation counts as work to carry, so a session with a note but no todo
+  list still arms; and a wake that never reports back is reaped as "lost".
 - In `resume` mode it runs the CLI itself. A headless resume does **not**
   inherit the session's permission mode, so unless one was set the resumed run
   will sit waiting for an approval nobody is there to give.

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

@@ -211,9 +211,10 @@ your own meter remains the best method anyone outside Anthropic has.
 own cache of the account meter, which refreshes on its own schedule - roughly
 hourly in practice, because the endpoint behind it rate-limits aggressive
 polling. Between refreshes every figure here is the last real reading plus
-arithmetic. That is why an old snapshot is reported as a floor with its age
+arithmetic. That is why an old snapshot is reported as an estimate with its age
 attached rather than dressed up as a current percentage, and why `/usage` is
-the one way to force a fresh reading.
+the one way to force a fresh reading. It is only called a floor when the
+correction has been refused and the raw snapshot is all that is shown.
 
 **A reset time can be in the past.** The cache refreshes when Claude Code
 talks to the API, so an idle spell leaves it behind. A window whose `resets_at`

package/skills/usage-limits/scripts/agy-hook.js

@@ -94,22 +94,19 @@ function toolNameOf(input) {
 // host that DOES have a meter, and because a ceiling that silently does
 // nothing on the day Antigravity starts publishing one would be worse.
 function percentNow(now) {
-  let worst = null;
+  // The same no-scan view and the same rule as the Claude Code pulse: the
+  // fullest window this agent can spend into, never a window that has reset.
   try {
-    const snapshot = usage.collect(now);
-    const utilization = snapshot && snapshot.utilization;
-    if (utilization && typeof utilization === 'object') {
-      for (const key of Object.keys(utilization)) {
-        const window = utilization[key];
-        if (!window || typeof window !== 'object') continue;
-        const value = Number(window.utilization);
-        if (Number.isFinite(value) && (worst === null || value > worst)) worst = value;
-      }
-    }
+    return ceiling.worstWindow(usage.snapshotWindows(usage.collect(now), now, null));
   } catch (err) {
     // No reading is a reason not to enforce, never a reason to throw.
+    return null;
   }
-  return worst;
+}
+
+// assess() takes the number and the name of the window it belongs to.
+function reading(worst) {
+  return { percent: worst ? worst.percent : null, label: worst ? worst.label : null };
 }
 
 async function run(now, input, argv) {
@@ -124,7 +121,7 @@ async function run(now, input, argv) {
   if (event === 'PreToolUse') {
     const tool = toolNameOf(input);
     if (!ceiling.isMultiplier(tool)) return {};
-    const at = ceiling.assess({ percent: percentNow(now), state: budget.state, env: process.env });
+    const at = ceiling.assess(Object.assign({ state: budget.state, env: process.env, sessionId }, reading(percentNow(now))));
     const call = ceiling.verdict(at, tool);
     if (call.decision !== 'deny') return {};
     return { decision: 'deny', reason: call.reason };
@@ -141,7 +138,7 @@ async function run(now, input, argv) {
       text = '';
     }
     const warning = ceiling.warning(
-      ceiling.assess({ percent: percentNow(now), state: budget.state, env: process.env })
+      ceiling.assess(Object.assign({ state: budget.state, env: process.env, sessionId }, reading(percentNow(now))))
     );
     const message = [text, warning].filter(Boolean).join(' ');
     return message ? { injectSteps: [{ ephemeralMessage: message }] } : { injectSteps: [] };