claude-usage-limits 1.2.0 → 1.4.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "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/README.md

@@ -167,6 +167,21 @@ node skills/usage-limits/scripts/usage.js
 node skills/usage-limits/scripts/usage.js --json
 ```
 
+## Which limit it watches
+
+Two windows run at once and the 5-hour one is usually what actually stops you,
+so it gets picked whenever it is tighter, and it wins a tie against the weekly
+window because the shorter window is the one hit first in practice.
+
+It is not forced, though. When the weekly window is genuinely the wall, at 99
+percent with minutes left, that is what gets reported. Forcing the 5-hour there
+would hide the limit about to stop the work, which is the same failure as
+ignoring it.
+
+A window with no recent spend to measure is ranked by how full it is rather
+than being skipped, so a 5-hour window sitting at 95 percent is never passed
+over just because nothing has gone through it in the last few minutes.
+
 ## When you keep typing
 
 Every message sent while work is already running starts another turn, and each
@@ -296,6 +311,7 @@ minute, so it costs about 400ms cold and 120ms warm.
 | `USAGE_LIMITS_FLOOR` | 40 | Below this, pace is ignored. |
 | `USAGE_LIMITS_AHEAD` | 15 | Points ahead of pace that count as burning fast. |
 | `USAGE_LIMITS_CACHE` | 60 | Seconds the measured half stays good for. |
+| `USAGE_LIMITS_FEW_TURNS` | 20 | Turn count at or below which the budget counts as tight. |
 
 ## What would this job cost
 
@@ -412,6 +428,13 @@ Good enough to plan with, not a bill. The honest caveats:
 - A model released after this table was written is priced at its family's
   average rate, and the report marks those rows with an asterisk rather than
   passing the guess off as a published price.
+- Time of day is not modelled. Anthropic used to shrink the five-hour limit
+  during peak hours, but removed that on 6 May 2026 for Pro and Max while
+  doubling the limits. If demand-based limits ever return, the numbers here
+  follow automatically, because they are calibrated from what your traffic did
+  to the meter rather than from an assumption about the clock.
+- The turn cost behind "turns of headroom" is a median over at least five
+  turns, so one compaction cannot define your pace.
 - The cache only refreshes when Claude Code talks to the API, so after a gap it
   can be hours old and its 5-hour window long since rolled over. Dropping that
   window would hide the limit that actually stops short work, so it gets rebuilt
@@ -448,7 +471,7 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-130 tests over the pricing, the window arithmetic, plan and credit detection,
+148 tests over the pricing, the window arithmetic, plan and credit detection,
 the status line, the before-prompt line, job forecasting, per-project
 attribution, the CLI, packaging, and the settings save/restore.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "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/references/how-it-works.md

@@ -124,6 +124,26 @@ window that no longer exists. Those are marked stale, excluded from the
 binding choice, and never used for projections, because treating one as
 current would report an empty budget at the exact moment the budget came back.
 
+**Time of day is not modelled, and does not need to be.** Anthropic used to
+shrink the Claude Code five-hour limit during peak hours, so the same work cost
+more of it in the afternoon. That ended on 6 May 2026, when the five-hour
+limits were doubled and, in Anthropic's words, they removed "the peak hours
+limit reduction on Claude Code for Pro and Max accounts". So there is no
+peak-hour penalty to model today.
+
+If one ever returns, nothing here needs changing. Every figure is calibrated
+from what your own traffic actually did to the meter, so if a point of budget
+starts costing more at four in the afternoon, the measured dollars-per-point
+moves with it and the headroom follows. That is the advantage of measuring
+rather than assuming: the tool does not need to know why a point got dearer.
+
+**One turn is not a pace.** The turn cost behind "turns of headroom" is the
+median of a sample, not the mean, and never from fewer than five turns. A
+compaction or a large file read can cost ten times an ordinary turn, and one of
+those landing in a thin sample once put a window that was 13 percent full at
+nine turns remaining. Thin samples widen to the whole window, and then to
+everything on record.
+
 **Pace is not a promise.** Turns left assumes the next turns look like the last
 hour's. A debugging spiral or a large file read breaks that assumption
 immediately. Re-run the report if the shape of the work changes.

package/skills/usage-limits/scripts/brief.js

@@ -28,6 +28,8 @@ const DEFAULTS = {
   // How long the measured part stays good for. Prompts often arrive in
   // bursts, and a transcript scan per prompt would be wasteful.
   cacheSeconds: 60,
+  // Few enough turns that the count itself is the warning.
+  fewTurns: 20,
 };
 
 function configDir() {
@@ -104,6 +106,7 @@ function settings() {
     floor: number(env.USAGE_LIMITS_FLOOR, DEFAULTS.floor),
     ahead: number(env.USAGE_LIMITS_AHEAD, DEFAULTS.ahead),
     cacheSeconds: number(env.USAGE_LIMITS_CACHE, DEFAULTS.cacheSeconds),
+    fewTurns: number(env.USAGE_LIMITS_FEW_TURNS, DEFAULTS.fewTurns),
   };
 }
 
@@ -117,16 +120,32 @@ function aheadOfPace(window, now) {
 }
 
 // Not whether to speak, which is always, but how hard to lean on it.
-function pressure(window, now, config) {
+// Not whether to speak, which is always, but how hard to lean on it.
+function pressure(window, now, config, turnsLeft) {
   if (!window || window.percentUsed === null || window.stale) return 'unknown';
-  if (window.verdict === 'exhausted') return 'gone';
+  if (window.verdict === 'exhausted' || window.percentUsed >= 100) return 'gone';
   if (window.verdict === 'runs-out') return 'tight';
-  if (window.percentUsed >= config.near) return 'tight';
 
-  const lead = aheadOfPace(window, now);
-  if (window.percentUsed >= config.floor && lead !== null && lead >= config.ahead) {
+  // A rebuilt figure only counts this machine, so it reads low. React to it
+  // sooner than to a figure the API actually reported.
+  const near = window.estimated ? Math.min(config.near, 70) : config.near;
+  if (window.percentUsed >= near) return 'tight';
+
+  // Turns are the number the work is planned in, so a short count is tight
+  // whatever the percentage says.
+  if (Number.isFinite(turnsLeft) && turnsLeft <= config.fewTurns) {
     return 'tight';
   }
+
+  // Pace only means something for a window with a real start. A rebuilt one
+  // is anchored at now minus its span, so it is always "fully elapsed" and
+  // the comparison can never fire.
+  if (!window.estimated) {
+    const lead = aheadOfPace(window, now);
+    if (window.percentUsed >= config.floor && lead !== null && lead >= config.ahead) {
+      return 'tight';
+    }
+  }
   return 'roomy';
 }
 
@@ -292,7 +311,7 @@ async function run(now, hookInput) {
     session: view.session,
     rebuilt: Boolean(binding && binding.estimated),
     snapshotAge: usage.formatDuration(base.snapshotAgeMs),
-    pressure: pressure(binding, now, config),
+    pressure: pressure(binding, now, config, view.turnsLeft),
   });
 }
 

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

@@ -355,6 +355,36 @@ function byModel(events) {
   return list;
 }
 
+const MIN_PACE_SAMPLE = 5;
+
+// The middle turn, not the mean, and never from a sample so small that one
+// turn defines the pace. A compaction or a big file read can cost ten times an
+// ordinary turn, and treating that as "the" turn cost sends the headroom
+// estimate swinging: a single $7 turn once put a 13% full window at nine turns
+// left. Too few recent turns to be sure, so widen to the whole window.
+function typicalTurnCost(recentEvents, windowEvents, allEvents, minSample) {
+  const floor = Number.isFinite(minSample) ? minSample : MIN_PACE_SAMPLE;
+
+  // What a turn costs is a fact about how you work, not about which budget it
+  // is being measured against, so a thin window borrows from a wider sample
+  // rather than inventing a figure from two turns.
+  const tiers = [recentEvents, windowEvents, allEvents];
+  let pool = [];
+  for (const tier of tiers) {
+    if (tier && tier.length >= floor) {
+      pool = tier;
+      break;
+    }
+    if (tier && tier.length > pool.length) pool = tier;
+  }
+  const costs = pool
+    .map((event) => event.cost)
+    .filter((cost) => Number.isFinite(cost) && cost > 0)
+    .sort((a, b) => a - b);
+  if (!costs.length) return null;
+  return costs[Math.floor(costs.length / 2)];
+}
+
 function dominantEffort(events) {
   const counts = new Map();
   for (const event of events) {
@@ -527,12 +557,11 @@ function buildWindow(spec, snapshot, events, now, options) {
     // The API reports whole numbers, so a low reading is a wide bracket.
     window.coarse = percent < 5;
 
-    const perTurn = recent.turns
-      ? recent.cost / recent.turns
-      : spent.cost / Math.max(spent.turns, 1);
-    window.percentPerTurn = perTurn / window.usdPerPercent;
+    const perTurn = typicalTurnCost(recentEvents, inWindow, events, MIN_PACE_SAMPLE);
+    window.percentPerTurn = perTurn === null ? null : perTurn / window.usdPerPercent;
+    window.typicalTurnUSD = perTurn;
     window.percentPerHour = window.recentUSDPerHour / window.usdPerPercent;
-    if (window.percentPerTurn > 0) {
+    if (window.percentPerTurn !== null && window.percentPerTurn > 0) {
       window.turnsLeft = Math.floor(window.percentLeft / window.percentPerTurn);
     }
     if (window.percentPerHour > 0) {
@@ -571,11 +600,27 @@ function bindingWindow(windows) {
   const live = fresh.length ? fresh : known;
   if (!live.length) return null;
 
-  const measured = live.filter((w) => w.headroomMs !== null);
-  if (measured.length) {
-    return measured.reduce((worst, w) => (w.headroomMs < worst.headroomMs ? w : worst));
-  }
-  return live.reduce((worst, w) => (w.percentUsed > worst.percentUsed ? w : worst));
+  // How soon this window stops the work. A window with no pace estimate is
+  // ranked by how full it is instead, because a nearly full window must never
+  // be passed over merely because nothing has been spent in it lately.
+  const soonest = (w) => {
+    if (Number.isFinite(w.headroomMs)) return w.headroomMs;
+    return w.percentUsed >= 90 ? 0 : Infinity;
+  };
+
+  return live.reduce((best, w) => {
+    const mine = soonest(w);
+    const theirs = soonest(best);
+    if (mine !== theirs) return mine < theirs ? w : best;
+
+    // Equally urgent: the shorter window is the one hit first in practice, so
+    // the 5-hour limit wins a tie against the weekly one.
+    const myspan = Number.isFinite(w.spanMs) ? w.spanMs : Infinity;
+    const theirspan = Number.isFinite(best.spanMs) ? best.spanMs : Infinity;
+    if (myspan !== theirspan) return myspan < theirspan ? w : best;
+
+    return w.percentUsed > best.percentUsed ? w : best;
+  });
 }
 
 function formatDuration(ms) {
@@ -1135,6 +1180,8 @@ module.exports = {
   buildWindows,
   bindingWindow,
   dominantEffort,
+  typicalTurnCost,
+  MIN_PACE_SAMPLE,
   formatDuration,
   formatUSD,
   formatCount,