claude-usage-limits 1.3.0 → 1.5.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.3.0",
+  "version": "1.5.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,26 @@ node skills/usage-limits/scripts/usage.js
 node skills/usage-limits/scripts/usage.js --json
 ```
 
+## When another Claude is working too
+
+Two Claude Code windows share one limit, so headroom measured in turns is
+optimistic while another session is also spending. It watches for that:
+
+```
+  Sharing       2 sessions have spent in the last 15m, splitting this budget 75% / 25%
+                The turns above are the whole window, not your slice of it.
+```
+
+and the before-prompt line says how many of those turns are actually yours:
+
+```
+about 38 turns of headroom (2 sessions active, roughly 10 of them yours)
+```
+
+The split comes from measured spend rather than an assumption that everyone is
+working equally hard, because they usually are not. A session that has gone
+quiet for a quarter of an hour is not counted as competing.
+
 ## Which limit it watches
 
 Two windows run at once and the 5-hour one is usually what actually stops you,
@@ -428,6 +448,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
@@ -464,7 +491,7 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-142 tests over the pricing, the window arithmetic, plan and credit detection,
+157 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.3.0",
+  "version": "1.5.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

@@ -215,7 +215,14 @@ function briefText(parts) {
   const described = describeWindow(parts.binding);
   if (described) bound.push(described + (parts.binding.stale ? '' : ' used'));
   if (Number.isFinite(parts.turnsLeft)) {
-    bound.push('about ' + parts.turnsLeft + ' turns of headroom');
+    // Another session spending the same budget means fewer of those turns are
+    // yours, so say both numbers rather than the flattering one.
+    const shared =
+      parts.sessions > 1 && Number.isFinite(parts.yourTurnsLeft)
+        ? ' (' + parts.sessions + ' sessions active, roughly ' + parts.yourTurnsLeft +
+          ' of them yours)'
+        : '';
+    bound.push('about ' + parts.turnsLeft + ' turns of headroom' + shared);
   }
   if (parts.resetsIn) bound.push('resets in ' + parts.resetsIn);
 
@@ -282,6 +289,7 @@ async function run(now, hookInput) {
       turnsLeft: binding && Number.isFinite(binding.turnsLeft) ? binding.turnsLeft : null,
       session: sessionSpend(events, sessionId),
       othersSummary: summariseOthers(windows, binding && binding.key),
+      sessions: usage.activeSessions(events, now, usage.CONCURRENT_WINDOW_MS),
       binding: binding
         ? {
             key: binding.key,
@@ -300,7 +308,13 @@ async function run(now, hookInput) {
   }
 
   const binding = view.binding;
+  const sessions = view.sessions || [];
+  const share = usage.shareOf(sessions, sessionId);
   return briefText({
+    sessions: sessions.length,
+    yourTurnsLeft: Number.isFinite(view.turnsLeft)
+      ? Math.max(1, Math.round(view.turnsLeft * share))
+      : null,
     binding,
     othersSummary: view.othersSummary,
     turnsLeft: 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) {
@@ -469,6 +499,39 @@ function forecastWindow(window, turns, rates) {
   };
 }
 
+const CONCURRENT_WINDOW_MS = 15 * MINUTE;
+
+// Sessions that have spent something recently. Two Claude Code windows share
+// one limit, so headroom measured in "turns" is optimistic when another one is
+// also working: the budget drains while you are not the one spending it.
+function activeSessions(events, now, windowMs) {
+  const since = now - (Number.isFinite(windowMs) ? windowMs : CONCURRENT_WINDOW_MS);
+  const bySession = new Map();
+
+  for (const event of events) {
+    if (event.at < since || event.at > now) continue;
+    const id = event.sessionId || 'unknown';
+    if (!bySession.has(id)) bySession.set(id, { sessionId: id, turns: 0, cost: 0 });
+    const row = bySession.get(id);
+    row.turns += 1;
+    row.cost += event.cost;
+  }
+
+  const rows = [...bySession.values()].sort((a, b) => b.cost - a.cost);
+  const total = rows.reduce((sum, row) => sum + row.cost, 0);
+  for (const row of rows) row.share = total > 0 ? row.cost / total : 0;
+  return rows;
+}
+
+// The slice of the shared budget this session is actually getting. With
+// another session spending half of it, only half those turns are yours.
+function shareOf(sessions, sessionId) {
+  if (!sessions || sessions.length < 2) return 1;
+  const mine = sessions.find((row) => row.sessionId === sessionId);
+  if (!mine) return 1 / sessions.length;
+  return mine.share > 0 ? mine.share : 1 / sessions.length;
+}
+
 // Everything the report needs about one limit window.
 function buildWindow(spec, snapshot, events, now, options) {
   const extra = options || {};
@@ -520,19 +583,28 @@ function buildWindow(spec, snapshot, events, now, options) {
   };
 
   // Calibrate against this account: how many dollars of measured traffic
-  // moved the meter one point.
-  if (percent !== null && percent > 0 && spent.cost > 0) {
-    window.usdPerPercent = spent.cost / percent;
+  // moved the meter one point. A rebuilt window hands its own figure in,
+  // because rounding to 0% would otherwise leave it unpriced and drop it out
+  // of the binding choice just after a reset.
+  const derived = percent !== null && percent > 0 && spent.cost > 0 ? spent.cost / percent : null;
+  const priced =
+    derived !== null
+      ? derived
+      : Number.isFinite(extra.usdPerPercent) && extra.usdPerPercent > 0
+        ? extra.usdPerPercent
+        : null;
+
+  if (percent !== null && priced !== null) {
+    window.usdPerPercent = priced;
     window.remainingUSD = window.usdPerPercent * window.percentLeft;
     // 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) {
@@ -744,7 +816,11 @@ function buildWindows(utilization, events, now) {
       { utilization: rebuilt.percentUsed, resets_at: null },
       events,
       now,
-      { estimated: true, windowStart: rebuilt.windowStart }
+      {
+        estimated: true,
+        windowStart: rebuilt.windowStart,
+        usdPerPercent: rebuilt.usdPerPercent,
+      }
     );
   }).filter(Boolean);
 }
@@ -770,6 +846,7 @@ async function report(now) {
     windows,
     binding,
     credits: creditsFrom(base.utilization),
+    sessions: activeSessions(events, now, CONCURRENT_WINDOW_MS),
     rates: costPercentiles(recentEvents.length >= 5 ? recentEvents : scoped),
     resumeAt: binding ? binding.resetsAt : null,
     models: byModel(scoped),
@@ -972,6 +1049,17 @@ function render(data) {
     lines.push('');
   }
 
+  if (data.sessions && data.sessions.length > 1) {
+    const split = data.sessions.map((row) => Math.round(row.share * 100) + '%').join(' / ');
+    lines.push(
+      '  Sharing       ' + data.sessions.length + ' sessions have spent in the last 15m, ' +
+        'splitting this budget ' + split
+    );
+    lines.push(
+      '                The turns above are the whole window, not your slice of it.'
+    );
+  }
+
   if (data.recent.turns) {
     lines.push(
       '  Recent pace   ' + data.recent.turns + ' turns in the last hour, ' +
@@ -1151,6 +1239,11 @@ module.exports = {
   buildWindows,
   bindingWindow,
   dominantEffort,
+  typicalTurnCost,
+  activeSessions,
+  shareOf,
+  CONCURRENT_WINDOW_MS,
+  MIN_PACE_SAMPLE,
   formatDuration,
   formatUSD,
   formatCount,