claude-usage-limits 1.1.1 → 1.1.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "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.",
   "author": {
     "name": "Ridelink",

package/README.md

@@ -349,6 +349,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 +365,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 +381,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,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "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.",
   "keywords": [
     "claude",

package/skills/usage-limits/SKILL.md

@@ -198,7 +198,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.
   }
@@ -186,24 +209,20 @@ 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];
@@ -243,6 +262,9 @@ module.exports = {
   summarise,
   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,