claude-usage-limits 1.0.0 → 1.1.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "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

@@ -1,5 +1,7 @@
 # usage-limits
 
+[![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.
 
@@ -71,7 +73,9 @@ npx claude-usage-limits --status
 npx claude-usage-limits lowpower on
 ```
 
-That runs the same code as the plugin. Node 18 or newer.
+That runs the same code as the plugin, from
+[claude-usage-limits](https://www.npmjs.com/package/claude-usage-limits) on
+npm. Node 18 or newer.
 
 To have Claude read the numbers and plan against them, install it properly.
 
@@ -136,6 +140,18 @@ The skill also requires Claude to say up front when a job will not fit in what
 is left, name what it is doing now, what it is leaving, and when the rest can
 happen, rather than starting and stopping halfway through an edit.
 
+## Releasing
+
+```
+npm version patch
+git push --follow-tags
+```
+
+Pushing the tag runs the tests and publishes to npm. That goes through npm's
+trusted publishing over OIDC, so there is no publish token stored in the repo
+or in CI. `npm version` also syncs the version in the plugin manifest, so the
+marketplace and the npm package never disagree about which release is current.
+
 ## Status line
 
 For a permanent readout instead of asking, point Claude Code's status line at
@@ -161,6 +177,67 @@ it runs in about a tenth of a second and is safe on every redraw. Use the full
 path rather than `~` if your shell does not expand it, and point it at the
 plugin copy instead if that is how you installed it.
 
+## It tells you where you stand, every time
+
+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.
+```
+
+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.
+
+When there is not, the line becomes a plan rather than a status:
+
+> 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.
+
+The wording changes with the pressure, not only the numbers. The trigger worth
+explaining is pace: two days into a week you should be near 29 percent spent, so
+60 percent means you will not last the week, and that is worth hearing at 60
+rather than at 85.
+
+It has to be cheap, because it runs on every prompt. The percentages come from
+one small file. The transcript scan behind "turns of headroom" is cached for a
+minute, so it costs about 400ms cold and 120ms warm.
+
+| Variable | Default | Effect |
+| --- | --- | --- |
+| `USAGE_LIMITS_BRIEF` | on | Set to `off` to turn the line off entirely. |
+| `USAGE_LIMITS_NEAR` | 80 | Percent used that always counts as tight. |
+| `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. |
+
+## What would this job cost
+
+```
+node skills/usage-limits/scripts/usage.js --forecast 15
+```
+
+```
+Forecast for 15 turns
+
+  Window                 Would cost    Leaves   Verdict
+  5-hour               7.4% to 8.4%       45%   fits
+  weekly               0.8% to 0.9%       83%   fits
+
+  Priced from 64 recent turns: $0.296 typical, $0.333 at the expensive end.
+
+  There is room for this. No need to work around the limit.
+```
+
+It prices turns at what turns have really cost on your account, and gives a
+range rather than one number, because a turn that reads three files costs many
+times one that answers from context. The upper end is the honest one for a long
+run, since turns get dearer as the context grows.
+
+
 ## Plans
 
 It reads which plan you are on and adjusts what it tells you, because the
@@ -274,9 +351,9 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-72 tests over the pricing, the window arithmetic, plan and credit detection,
-the status line, per-project attribution, the CLI, and the settings
-save/restore.
+105 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.
 
 ## Status
 

package/bin/cli.js

@@ -10,6 +10,7 @@ const HELP = `claude-usage-limits - how much Claude Code usage is left, and whet
   claude-usage-limits                     the report
   claude-usage-limits --json              the same numbers, machine readable
   claude-usage-limits --status            one short line, for a status line
+  claude-usage-limits --forecast 15       what a 15 turn job would cost
 
   claude-usage-limits lowpower status     show the current effort setting
   claude-usage-limits lowpower on         lower effortLevel, remembering the old value

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "description": "Tells Claude how much usage budget is left, but only when it is tight enough to change what can be done.",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/skills/usage-limits/scripts/brief.js\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "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",
@@ -31,6 +31,7 @@
     "bin/",
     "skills/",
     "commands/",
+    "hooks/",
     ".claude-plugin/"
   ],
   "engines": {
@@ -38,6 +39,7 @@
   },
   "scripts": {
     "test": "node --test",
-    "usage": "node bin/cli.js"
+    "usage": "node bin/cli.js",
+    "version": "node tools/sync-version.js && git add .claude-plugin/plugin.json"
   }
 }

package/skills/usage-limits/SKILL.md

@@ -92,6 +92,47 @@ yourself: Claude Code announces it and asks before drawing on credits, and
 repeating that only adds noise. Just factor it into the plan, and take the
 user's answer to that prompt as the decision.
 
+## Opening with the budget
+
+Start every reply with one line saying where the budget stands and whether what
+was asked fits. The hook puts the numbers in front of you before the prompt, so
+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.
+
+When it does not fit, that line becomes the plan:
+
+> 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.
+
+What makes the second one useful is the split, not the percentage. "78% used"
+is not something anyone can act on. "This fits, that does not, here is the
+order" is.
+
+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.
+
+### Pricing the job before starting it
+
+Size the work in turns using the table above, then price it:
+
+```
+node scripts/usage.js --forecast 15
+```
+
+That converts turns into points of each window using what turns have really
+cost on this account, and reports a range rather than a single number, because
+a turn that reads three files costs many times one that answers from context.
+The upper end is the honest one for a long run, since turns get dearer as the
+context grows.
+
+Reach for it whenever the answer to "will this finish" is not obvious.
+
+
 ## 4. Low power
 
 Two halves, and the second one is the half that actually binds.

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

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+'use strict';
+
+// The hook entry point. Runs before each prompt is handled and puts one line
+// into Claude's context saying where the budget stands, what this session has
+// cost so far, and to open the reply with it.
+//
+// It runs on every prompt, so two things matter more than features: it has to
+// be one line, and it has to be fast. The expensive half is cached for a
+// minute, and the numbers that change every turn are the cheap ones.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const usage = require('./usage.js');
+
+const SECOND = 1000;
+const DAY = 24 * 60 * 60 * 1000;
+
+const DEFAULTS = {
+  // Close enough to the wall that the wording should change.
+  near: 80,
+  // Below this, pace is not worth worrying about.
+  floor: 40,
+  // Points of budget spent beyond the share of the window that has elapsed.
+  ahead: 15,
+  // How long the measured part stays good for. Prompts often arrive in
+  // bursts, and a transcript scan per prompt would be wasteful.
+  cacheSeconds: 60,
+};
+
+function configDir() {
+  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+}
+
+function cacheFile() {
+  return path.join(configDir(), 'usage-limits-brief.json');
+}
+
+function readCache() {
+  try {
+    return JSON.parse(fs.readFileSync(cacheFile(), 'utf8'));
+  } catch (err) {
+    return null;
+  }
+}
+
+function writeCache(value) {
+  try {
+    fs.mkdirSync(path.dirname(cacheFile()), { recursive: true });
+    fs.writeFileSync(cacheFile(), JSON.stringify(value), 'utf8');
+  } catch (err) {
+    // A cache miss costs a scan. A crash costs the prompt. Prefer the scan.
+  }
+}
+
+function settings() {
+  const env = process.env;
+  const number = (value, fallback) => {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+  };
+  return {
+    near: number(env.USAGE_LIMITS_NEAR, DEFAULTS.near),
+    floor: number(env.USAGE_LIMITS_FLOOR, DEFAULTS.floor),
+    ahead: number(env.USAGE_LIMITS_AHEAD, DEFAULTS.ahead),
+    cacheSeconds: number(env.USAGE_LIMITS_CACHE, DEFAULTS.cacheSeconds),
+  };
+}
+
+// How far ahead of the clock the spending is. A weekly window two days in
+// should be near 29 percent spent; 60 percent means it will not last.
+function aheadOfPace(window, now) {
+  if (!window || !window.spanMs || !Number.isFinite(window.windowStart)) return null;
+  if (window.percentUsed === null) return null;
+  const elapsed = ((now - window.windowStart) / window.spanMs) * 100;
+  return window.percentUsed - Math.min(100, Math.max(0, elapsed));
+}
+
+// Not whether to speak, which is always, but how hard to lean on it.
+function pressure(window, now, config) {
+  if (!window || window.percentUsed === null || window.stale) return 'unknown';
+  if (window.verdict === 'exhausted') 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) {
+    return 'tight';
+  }
+  return 'roomy';
+}
+
+// The hook is handed JSON on stdin. The session id in it is what lets this
+// report what the current session has cost rather than the whole window.
+function readHookInput() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve(null);
+
+    let raw = '';
+    let settled = false;
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      try {
+        resolve(raw ? JSON.parse(raw) : null);
+      } catch (err) {
+        resolve(null);
+      }
+    };
+
+    // A hook must never hang the prompt waiting for input that is not coming.
+    const timer = setTimeout(done, 500);
+    if (timer.unref) timer.unref();
+
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      raw += chunk;
+    });
+    process.stdin.on('end', done);
+    process.stdin.on('error', done);
+  });
+}
+
+function sessionSpend(events, sessionId) {
+  if (!sessionId) return null;
+  let cost = 0;
+  let turns = 0;
+  for (const event of events) {
+    if (event.sessionId !== sessionId) continue;
+    cost += event.cost;
+    turns += 1;
+  }
+  return turns ? { turns, cost } : null;
+}
+
+function summarise(windows) {
+  return windows
+    .filter((window) => window.percentUsed !== null)
+    .map((window) =>
+      window.stale
+        ? window.label + ' rolling over'
+        : window.label + ' ' + window.percentUsed + '%'
+    )
+    .join(', ');
+}
+
+function briefText(parts) {
+  const facts = [];
+  if (parts.windowSummary) facts.push(parts.windowSummary);
+  if (Number.isFinite(parts.turnsLeft)) {
+    facts.push('about ' + parts.turnsLeft + ' turns of headroom');
+  }
+  if (parts.resetsIn) facts.push('resets in ' + parts.resetsIn);
+  if (parts.session) {
+    facts.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 ' +
+        'what you will do now and what you will leave for after the reset. ' +
+        'Do not start work that clearly will not finish.'
+      : '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;
+}
+
+async function run(now, hookInput) {
+  if (String(process.env.USAGE_LIMITS_BRIEF || '').toLowerCase() === 'off') return '';
+
+  const config = settings();
+  const base = usage.collect(now);
+  if (!base.utilization) return '';
+
+  const sessionId = hookInput && hookInput.session_id ? hookInput.session_id : null;
+
+  // The percentages are cheap: one small file, no transcripts.
+  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;
+
+  let turnsLeft = fresh ? cached.turnsLeft : null;
+  let session = fresh ? cached.session : null;
+  let windows = cheap;
+
+  if (!fresh) {
+    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 });
+  }
+
+  const binding = usage.bindingWindow(windows) || windows[0];
+
+  return briefText({
+    windowSummary: summarise(windows),
+    turnsLeft,
+    resetsIn:
+      binding && !binding.stale && binding.msToReset !== null
+        ? usage.formatDuration(binding.msToReset)
+        : null,
+    session,
+    pressure: pressure(binding, now, config),
+  });
+}
+
+if (require.main === module) {
+  readHookInput()
+    .then((input) => run(Date.now(), input))
+    .then(
+      (text) => {
+        if (text) process.stdout.write(text + '\n');
+        process.exit(0);
+      },
+      () => {
+        // A hook that throws must not disrupt the prompt it runs before.
+        process.exit(0);
+      }
+    );
+}
+
+module.exports = {
+  DEFAULTS,
+  aheadOfPace,
+  pressure,
+  sessionSpend,
+  summarise,
+  briefText,
+  settings,
+  run,
+  cacheFile,
+};

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

@@ -217,6 +217,7 @@ function eventFrom(line, seen, project) {
     tokens: tokensOf(entry.message.usage),
     parts: tokenParts(entry.message.usage),
     project: project || null,
+    sessionId: entry.sessionId || null,
   };
 }
 
@@ -396,6 +397,46 @@ function creditsFrom(utilization) {
   };
 }
 
+// Turn cost is not a single number, it is a spread: a turn that reads three
+// files costs many times one that answers from context. A median alone
+// under-promises on the expensive half, so carry a high end too.
+function costPercentiles(events) {
+  const costs = (events || [])
+    .map((event) => event.cost)
+    .filter((cost) => Number.isFinite(cost) && cost > 0)
+    .sort((a, b) => a - b);
+  if (!costs.length) return null;
+
+  const at = (fraction) => costs[Math.min(costs.length - 1, Math.floor(fraction * costs.length))];
+  return { median: at(0.5), high: at(0.8), sample: costs.length };
+}
+
+// What a job of this many turns would take out of one window.
+function forecastWindow(window, turns, rates) {
+  if (!window || !rates || !window.usdPerPercent || window.stale) return null;
+  if (!Number.isFinite(turns) || turns <= 0) return null;
+
+  const usdLow = turns * rates.median;
+  const usdHigh = turns * rates.high;
+  const percentLow = usdLow / window.usdPerPercent;
+  const percentHigh = usdHigh / window.usdPerPercent;
+
+  return {
+    key: window.key,
+    label: window.label,
+    turns,
+    usdLow,
+    usdHigh,
+    percentLow,
+    percentHigh,
+    // The pessimistic cost is what decides whether it fits, so the room left
+    // over is measured against that.
+    leaves: window.percentLeft - percentHigh,
+    fits: percentHigh <= window.percentLeft,
+    tight: percentHigh > window.percentLeft * 0.75 && percentHigh <= window.percentLeft,
+  };
+}
+
 // Everything the report needs about one limit window.
 function buildWindow(spec, snapshot, events, now) {
   const percent =
@@ -420,6 +461,7 @@ function buildWindow(spec, snapshot, events, now) {
     resetsAt: hasReset ? resetsAt : null,
     msToReset: hasReset ? resetsAt - now : null,
     windowStart: start,
+    spanMs: spec.span,
     spentUSD: spent.cost,
     spentTokens: spent.tokens,
     turns: spent.turns,
@@ -626,6 +668,7 @@ async function report(now) {
     windows,
     binding,
     credits: creditsFrom(base.utilization),
+    rates: costPercentiles(recentEvents.length >= 5 ? recentEvents : scoped),
     resumeAt: binding ? binding.resetsAt : null,
     models: byModel(scoped),
     projects: byProject(scoped),
@@ -861,6 +904,79 @@ function render(data) {
   return lines.join('\n');
 }
 
+function formatPercent(value) {
+  if (!Number.isFinite(value)) return '-';
+  if (value >= 10) return Math.round(value) + '%';
+  return value.toFixed(1) + '%';
+}
+
+function renderForecast(data, turns) {
+  const lines = [];
+  lines.push('Forecast for ' + turns + ' turns');
+  lines.push('');
+
+  if (!Number.isFinite(turns) || turns <= 0) {
+    lines.push('  Give a number of turns, for example --forecast 15.');
+    return lines.join('\n');
+  }
+  if (!data.rates) {
+    lines.push('  Nothing recent to price this against yet. Do some work in this');
+    lines.push('  session first, then ask again.');
+    return lines.join('\n');
+  }
+
+  const rows = data.windows
+    .map((window) => forecastWindow(window, turns, data.rates))
+    .filter(Boolean);
+
+  if (!rows.length) {
+    lines.push('  No window has enough measured spend to price a forecast against.');
+    return lines.join('\n');
+  }
+
+  lines.push(
+    '  ' + pad('Window', 15) + padLeft('Would cost', 18) + padLeft('Leaves', 10) + '   Verdict'
+  );
+  for (const row of rows) {
+    const verdict = row.fits ? (row.tight ? 'fits, barely' : 'fits') : 'does not fit';
+    lines.push(
+      '  ' + pad(row.label, 15) +
+        padLeft(formatPercent(row.percentLow) + ' to ' + formatPercent(row.percentHigh), 18) +
+        padLeft(formatPercent(Math.max(0, row.leaves)), 10) +
+        '   ' + verdict
+    );
+  }
+  lines.push('');
+  lines.push(
+    '  Priced from ' + data.rates.sample + ' recent turns: ' +
+      formatUSD(data.rates.median) + ' typical, ' + formatUSD(data.rates.high) +
+      ' at the expensive end.'
+  );
+
+  const blocked = rows.filter((row) => !row.fits);
+  const tight = rows.filter((row) => row.fits && row.tight);
+  lines.push('');
+  if (blocked.length) {
+    lines.push(
+      '  The ' + blocked[0].label + ' window does not cover this. Cut it down or ' +
+        'split it at a clean boundary rather than starting and getting cut off.'
+    );
+  } else if (tight.length) {
+    lines.push(
+      '  It fits, but only if nothing goes wrong. Order the work so the valuable ' +
+        'part lands first.'
+    );
+  } else {
+    lines.push('  There is room for this. No need to work around the limit.');
+  }
+  lines.push(
+    '  Turns get dearer as context grows, so the higher number is the honest one ' +
+      'for a long run.'
+  );
+
+  return lines.join('\n');
+}
+
 async function main(argv) {
   // The status line runs on every redraw, so it must not scan transcripts.
   if (argv.indexOf('--status') !== -1) {
@@ -870,6 +986,20 @@ async function main(argv) {
 
   const wantsJson = argv.indexOf('--json') !== -1;
   const data = await report(Date.now());
+
+  const forecastAt = argv.indexOf('--forecast');
+  if (forecastAt !== -1) {
+    const turns = Number(argv[forecastAt + 1]);
+    if (wantsJson) {
+      const rows = data.windows
+        .map((window) => forecastWindow(window, turns, data.rates))
+        .filter(Boolean);
+      process.stdout.write(JSON.stringify({ turns, rates: data.rates, windows: rows }, null, 2) + '\n');
+    } else {
+      process.stdout.write(renderForecast(data, turns) + '\n');
+    }
+    return 0;
+  }
   if (wantsJson) {
     process.stdout.write(JSON.stringify(data, null, 2) + '\n');
   } else {
@@ -893,6 +1023,7 @@ module.exports = {
   costOf,
   tokensOf,
   eventFrom,
+  readEvents,
   buildWindow,
   buildWindows,
   bindingWindow,
@@ -905,6 +1036,9 @@ module.exports = {
   report,
   collect,
   detectPlan,
+  costPercentiles,
+  forecastWindow,
+  renderForecast,
   creditsFrom,
   formatClock,
   statusLine,