claude-usage-limits 1.1.1 → 1.1.3

package/.claude-plugin/marketplace.json

@@ -9,9 +9,14 @@
     {
       "name": "usage-limits",
       "source": "./",
-      "description": "Reads how much of your Claude Code usage limit is left, converts it into turns of headroom, and plans the work to fit inside it.",
+      "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.",
       "category": "productivity",
-      "tags": ["usage", "limits", "cost", "planning"],
+      "tags": [
+        "usage",
+        "limits",
+        "cost",
+        "planning"
+      ],
       "license": "MIT"
     }
   ]

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.1.1",
-  "description": "Reads how much of your Claude Code usage limit is left, converts it into turns of headroom, and plans the work to fit inside it. Includes a low power switch that keeps spending down even at high effort.",
+  "version": "1.1.3",
+  "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",
     "url": "https://github.com/ridelink0"

package/README.md

@@ -2,14 +2,46 @@
 
 [![npm](https://img.shields.io/npm/v/claude-usage-limits)](https://www.npmjs.com/package/claude-usage-limits)
 
-A Claude Code plugin that reads how much of your usage limit is left and plans
-the work to fit inside it.
+Most usage tools for Claude Code show **you** the numbers. This one shows them
+to **Claude**, before every prompt, and changes what it does about them.
 
-Claude Code already knows how much of your 5-hour and weekly limit you have
-spent. It caches the numbers locally and shows them when you ask. What it does
-not do on its own is notice that the job in front of it is bigger than the
-budget behind it, and adjust. This adds that: a report you can act on, and a
-set of rules for what to do when the answer is "not enough".
+Claude Code already knows how much of your 5-hour and weekly limit is gone. It
+caches those numbers locally and will show them if you ask. What it does not do
+is notice that the job in front of it is larger than the budget behind it. So
+it starts anyway, and stops halfway through an edit.
+
+This puts the budget in front of Claude before your prompt lands, so the reply
+opens with the answer instead:
+
+> The weekly window has about 22 turns left. That covers the parser change and
+> its tests, but not the migration or the docs pass, so I will do the first two
+> and leave the rest for after the reset at 09:00.
+
+Nobody read a chart to get that. The numbers reached the model, not you.
+
+## How this differs from a usage dashboard
+
+There are a lot of good tools that read the same local files this does and draw
+you a picture: status lines, menu bar apps, terminal dashboards. They are worth
+having, and this is not trying to replace them. The difference is who the
+output is for.
+
+| A usage dashboard | This |
+| --- | --- |
+| Renders numbers for a person to read | Puts numbers in the model's context |
+| You notice, then you interrupt | Claude notices, and adjusts on its own |
+| Tells you 78 percent is gone | Tells you 22 turns are left, and whether what you asked for fits in them |
+| Runs beside Claude Code | Runs inside it, as a skill and a hook |
+| Shows what already happened | Says what to do now, and what to drop |
+
+A percentage is a fact about the past. The useful question is whether the thing
+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.
 
 ## What it prints
 
@@ -206,13 +238,19 @@ Installed as a plugin, a hook measures the budget before each prompt and puts
 one line into Claude's context:
 
 ```
-[usage-limits] 5-hour 47%, weekly 16%, about 75 turns of headroom, resets in
-3h 52m, this session 229 turns, $64.16.
+[usage-limits] binding window is 5-hour 47% used, about 75 turns of headroom,
+resets in 3h 52m. Other windows: weekly 16%. This session: 229 turns, $64.16.
 ```
 
+It names the window that will stop the work first and hangs the figures off
+that one. Two windows run at once and they are rarely in the same place, so
+"weekly 16%" sitting next to "75 turns" would read as far more room than
+exists.
+
 Claude opens with it. When there is room that is a single line and it moves on:
 
-> Weekly is at 16%, 5-hour at 47%, about 75 turns of headroom. This fits easily.
+> The 5-hour window is the binding one: 47% used, about 75 turns of headroom.
+> This fits easily.
 
 When there is not, the line becomes a plan rather than a status:
 
@@ -349,6 +387,9 @@ Good enough to plan with, not a bill. The honest caveats:
   a percentage of the limit. On a subscription plan you are not billed them.
 - Turns left assumes the next turns look like the last hour's. A debugging
   spiral breaks that assumption immediately.
+- 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.
 - The cache only refreshes when Claude Code talks to the API, so after an idle
   spell a window can sit past its own reset time. When that happens the report
   says `stale` and the status line says `rolling` rather than reporting a
@@ -362,9 +403,13 @@ names, the formulas, and the rest of it.
 ```
 .claude-plugin/plugin.json        plugin manifest
 .claude-plugin/marketplace.json   lets the repo serve itself
-skills/usage-limits/SKILL.md            what Claude reads
-skills/usage-limits/scripts/            the two scripts
-skills/usage-limits/references/         the longer notes
+skills/usage-limits/SKILL.md      what Claude reads
+skills/usage-limits/scripts/      usage.js, lowpower.js, brief.js
+skills/usage-limits/references/   the longer notes
+hooks/hooks.json                  runs brief.js before each prompt
+commands/check.md                 the /usage-limits:check command
+bin/cli.js                        the npx entry point
+tools/sync-version.js             keeps the manifest version in step
 test/                             node --test, no dependencies
 ```
 
@@ -374,7 +419,7 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-105 tests over the pricing, the window arithmetic, plan and credit detection,
+119 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,7 +1,7 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.1.1",
-  "description": "See how much of your Claude Code usage limit is left as turns of work rather than a percentage, and plan the job to fit inside it.",
+  "version": "1.1.3",
+  "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",
     "claude-code",

package/skills/usage-limits/SKILL.md

@@ -100,7 +100,8 @@ there is nothing to go and look up.
 
 When there is room, one line, then get on with it:
 
-> Weekly is at 16%, 5-hour at 47%, about 75 turns of headroom. This fits easily.
+> The 5-hour window is the binding one: 47% used, about 75 turns of headroom.
+> This fits easily.
 
 When it does not fit, that line becomes the plan:
 
@@ -116,6 +117,13 @@ Keep it to one line unless the work genuinely does not fit. The budget note is
 a header, not a section, and it must never push the actual answer down the
 page.
 
+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
+other window's percentage next to those figures claims far more room than
+exists, and that is how a session ends mid-edit while the weekly number still
+looks comfortable.
+
 ### Pricing the job before starting it
 
 Size the work in turns using the table above, then price it:
@@ -198,7 +206,8 @@ a turn, which is the thing it is trying to save.
 
 | Path | What it is |
 | --- | --- |
-| `scripts/usage.js` | The report. `--json` for raw fields, `--status` for a one-line status line readout that skips the transcript scan. |
+| `scripts/usage.js` | The report. `--json` for raw fields, `--status` for a one-line readout that skips the transcript scan, `--forecast N` for what an N turn job would cost. |
+| `scripts/brief.js` | What the hook runs before each prompt. Not meant to be called by hand. |
 | `scripts/lowpower.js` | `status`, `on`, `off`. Restores what it replaced. |
 | `references/tactics.md` | Every lever that lowers cost, and why it works. |
 | `references/how-it-works.md` | Where the numbers come from and where they are soft. |

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

@@ -131,6 +131,18 @@ immediately. Re-run the report if the shape of the work changes.
 ## Keeping it accurate
 
 The rate table in `scripts/usage.js` is a plain object at the top of the file.
-When new models ship, add a row. An unknown id falls back to the family it
-names (`opus`, `sonnet`, `haiku`, `fable`) and then to Opus rates, so a missing
-row degrades to an estimate rather than a crash.
+When new models ship, add a row.
+
+Until someone does, a model this table has not seen is priced at the average of
+the family its name contains: an unreleased `claude-opus-5-2` is charged at the
+mean of every Opus rate on record. Averaging assumes nothing about which
+direction prices moved, which is why it beats pinning to whichever release
+happened to be newest when the table was written.
+
+A name with no recognisable family falls back to Opus rates. That is a
+deliberate choice rather than a neutral one: over-estimating cost understates
+your headroom, and being told you have less room than you do is the safe way to
+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.

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

@@ -38,18 +38,41 @@ function cacheFile() {
   return path.join(configDir(), 'usage-limits-brief.json');
 }
 
+// One slot per session. A single shared slot meant that alternating between
+// two Claude Code windows invalidated the cache on every prompt, so neither
+// ever got a hit and both paid for a full scan each time.
+const KEEP_SESSIONS = 5;
+
 function readCache() {
   try {
-    return JSON.parse(fs.readFileSync(cacheFile(), 'utf8'));
+    const parsed = JSON.parse(fs.readFileSync(cacheFile(), 'utf8'));
+    return parsed && typeof parsed === 'object' ? parsed : {};
   } catch (err) {
-    return null;
+    return {};
   }
 }
 
-function writeCache(value) {
+function pickCached(all, sessionId, now, ttlMs) {
+  const entry = all ? all[sessionId || '_'] : null;
+  if (!entry || !Number.isFinite(entry.at)) return null;
+  return now - entry.at < ttlMs ? entry : null;
+}
+
+// Keep the newest few so a machine with many sessions does not grow the file
+// without bound.
+function mergeCache(all, sessionId, entry, keep) {
+  const next = Object.assign({}, all || {});
+  next[sessionId || '_'] = entry;
+  const ordered = Object.keys(next).sort((a, b) => (next[b].at || 0) - (next[a].at || 0));
+  const trimmed = {};
+  for (const key of ordered.slice(0, keep || KEEP_SESSIONS)) trimmed[key] = next[key];
+  return trimmed;
+}
+
+function writeCache(all) {
   try {
     fs.mkdirSync(path.dirname(cacheFile()), { recursive: true });
-    fs.writeFileSync(cacheFile(), JSON.stringify(value), 'utf8');
+    fs.writeFileSync(cacheFile(), JSON.stringify(all), 'utf8');
   } catch (err) {
     // A cache miss costs a scan. A crash costs the prompt. Prefer the scan.
   }
@@ -135,33 +158,47 @@ function sessionSpend(events, sessionId) {
   return turns ? { turns, cost } : null;
 }
 
-function summarise(windows) {
+function describeWindow(window) {
+  if (!window) return null;
+  return window.stale
+    ? window.label + ' rolling over'
+    : window.label + ' ' + window.percentUsed + '%';
+}
+
+// Everything except the window that will actually stop the work.
+function summariseOthers(windows, bindingKey) {
   return windows
-    .filter((window) => window.percentUsed !== null)
-    .map((window) =>
-      window.stale
-        ? window.label + ' rolling over'
-        : window.label + ' ' + window.percentUsed + '%'
-    )
+    .filter((window) => window.percentUsed !== null && window.key !== bindingKey)
+    .map(describeWindow)
     .join(', ');
 }
 
 function briefText(parts) {
-  const facts = [];
-  if (parts.windowSummary) facts.push(parts.windowSummary);
+  // The turns and the reset time belong to one specific window. Listing every
+  // window and then the numbers invites reading them against the wrong one, so
+  // the binding window is named and its figures are attached to it.
+  const bound = [];
+  const described = describeWindow(parts.binding);
+  if (described) bound.push(described + (parts.binding.stale ? '' : ' used'));
   if (Number.isFinite(parts.turnsLeft)) {
-    facts.push('about ' + parts.turnsLeft + ' turns of headroom');
+    bound.push('about ' + parts.turnsLeft + ' turns of headroom');
   }
-  if (parts.resetsIn) facts.push('resets in ' + parts.resetsIn);
+  if (parts.resetsIn) bound.push('resets in ' + parts.resetsIn);
+
+  const sentences = [];
+  sentences.push(
+    bound.length
+      ? '[usage-limits] binding window is ' + bound.join(', ') + '.'
+      : '[usage-limits] no usable window reading.'
+  );
+  if (parts.othersSummary) sentences.push('Other windows: ' + parts.othersSummary + '.');
   if (parts.session) {
-    facts.push(
-      'this session ' + parts.session.turns + ' turns, ' +
-        usage.formatUSD(parts.session.cost)
+    sentences.push(
+      'This session: ' + parts.session.turns + ' turns, ' +
+        usage.formatUSD(parts.session.cost) + '.'
     );
   }
 
-  const head = '[usage-limits] ' + facts.join(', ') + '.';
-
   const instruction =
     parts.pressure === 'tight' || parts.pressure === 'gone'
       ? 'Open your reply with one line on where this leaves the budget, then say ' +
@@ -170,7 +207,14 @@ function briefText(parts) {
       : 'Open your reply with one short line stating this and confirming the ' +
         'request fits, then get on with the work. Keep it to a single line.';
 
-  return head + '\n' + instruction;
+  // The mistake this guards against: quoting the roomiest window and pinning
+  // the binding window figures to it.
+  const care =
+    ' Quote the binding window, not whichever one has the most left. The turns ' +
+    'and reset time above belong to the binding window alone; do not read them ' +
+    'against another window percentage.';
+
+  return sentences.join(' ') + '\n' + instruction + care;
 }
 
 async function run(now, hookInput) {
@@ -186,30 +230,27 @@ async function run(now, hookInput) {
   const cheap = usage.buildWindows(base.utilization, [], now);
   if (!cheap.length) return '';
 
-  const cached = readCache();
-  const fresh =
-    cached &&
-    Number.isFinite(cached.at) &&
-    now - cached.at < config.cacheSeconds * SECOND &&
-    cached.sessionId === sessionId;
+  const all = readCache();
+  const cached = pickCached(all, sessionId, now, config.cacheSeconds * SECOND);
 
-  let turnsLeft = fresh ? cached.turnsLeft : null;
-  let session = fresh ? cached.session : null;
+  let turnsLeft = cached ? cached.turnsLeft : null;
+  let session = cached ? cached.session : null;
   let windows = cheap;
 
-  if (!fresh) {
+  if (!cached) {
     const events = await usage.readEvents(now - 8 * DAY);
     windows = usage.buildWindows(base.utilization, events, now);
     const binding = usage.bindingWindow(windows);
     turnsLeft = binding && Number.isFinite(binding.turnsLeft) ? binding.turnsLeft : null;
     session = sessionSpend(events, sessionId);
-    writeCache({ at: now, turnsLeft, session, sessionId });
+    writeCache(mergeCache(all, sessionId, { at: now, turnsLeft, session }, KEEP_SESSIONS));
   }
 
   const binding = usage.bindingWindow(windows) || windows[0];
 
   return briefText({
-    windowSummary: summarise(windows),
+    binding,
+    othersSummary: summariseOthers(windows, binding && binding.key),
     turnsLeft,
     resetsIn:
       binding && !binding.stale && binding.msToReset !== null
@@ -240,9 +281,13 @@ module.exports = {
   aheadOfPace,
   pressure,
   sessionSpend,
-  summarise,
+  describeWindow,
+  summariseOthers,
   briefText,
   settings,
+  pickCached,
+  mergeCache,
+  KEEP_SESSIONS,
   run,
   cacheFile,
 };

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

@@ -37,8 +37,43 @@ const RATES = {
   'claude-sonnet-4-6': { input: 3, output: 15 },
   'claude-haiku-4-5': { input: 1, output: 5 },
 };
+// A model can ship before this table knows about it. Rather than refusing to
+// price it, fall back to the average of the family it names. Averaging assumes
+// nothing about which direction prices moved, unlike pinning to one release.
+// An unrecognised family falls back to Opus rates on purpose: over-estimating
+// cost understates headroom, and that is the safe direction for a budget.
+const FAMILIES = ['fable', 'mythos', 'opus', 'sonnet', 'haiku'];
 const FALLBACK_RATE = { input: 5, output: 25 };
 
+function familyOf(model) {
+  const id = String(model || '').toLowerCase();
+  for (const family of FAMILIES) {
+    // Mythos is priced with Fable, so it counts as the same family.
+    if (id.indexOf(family) !== -1) return family === 'mythos' ? 'fable' : family;
+  }
+  return null;
+}
+
+function familyAverage(family, table) {
+  if (!family) return null;
+  const rates = table || RATES;
+  const members = Object.keys(rates).filter((id) => familyOf(id) === family);
+  if (!members.length) return null;
+
+  let input = 0;
+  let output = 0;
+  for (const id of members) {
+    input += rates[id].input;
+    output += rates[id].output;
+  }
+  return { input: input / members.length, output: output / members.length };
+}
+
+// Whether the price came from the table or from an assumption.
+function isKnownModel(model) {
+  return Object.prototype.hasOwnProperty.call(RATES, String(model || '').toLowerCase());
+}
+
 // Cache traffic is priced as a multiple of the input rate.
 const CACHE_WRITE_5M = 1.25;
 const CACHE_WRITE_1H = 2;
@@ -129,11 +164,7 @@ function readJson(file) {
 function rateFor(model) {
   const id = String(model || '').toLowerCase();
   if (RATES[id]) return RATES[id];
-  if (id.includes('fable') || id.includes('mythos')) return RATES['claude-fable-5'];
-  if (id.includes('opus')) return RATES['claude-opus-5'];
-  if (id.includes('sonnet')) return RATES['claude-sonnet-5'];
-  if (id.includes('haiku')) return RATES['claude-haiku-4-5'];
-  return FALLBACK_RATE;
+  return familyAverage(familyOf(id)) || FALLBACK_RATE;
 }
 
 // Cost of one assistant turn, in USD, from its usage record.
@@ -300,6 +331,7 @@ function byModel(events) {
     if (!rows.has(id)) {
       rows.set(id, {
         model: id,
+        estimated: !isKnownModel(id),
         turns: 0,
         tokens: 0,
         cost: 0,
@@ -829,12 +861,16 @@ function render(data) {
     );
     for (const row of data.models) {
       lines.push(
-        '  ' + pad('  ' + row.model, 24) + padLeft(row.turns, 7) +
+        '  ' + pad('  ' + row.model + (row.estimated ? ' *' : ''), 24) +
+          padLeft(row.turns, 7) +
           padLeft(formatTokens(row.tokens), 10) +
           padLeft(formatTokens(row.parts.output), 9) +
           padLeft(Math.round(row.share * 100) + '%', 8)
       );
     }
+    if (data.models.some((row) => row.estimated)) {
+      lines.push('    * no published rate for this one yet, priced at the family average');
+    }
     if (data.tokens) {
       lines.push(
         '    Tokens  input ' + formatTokens(data.tokens.input) +
@@ -1020,6 +1056,9 @@ module.exports = {
   RATES,
   WINDOWS,
   rateFor,
+  familyOf,
+  familyAverage,
+  isKnownModel,
   costOf,
   tokensOf,
   eventFrom,