claude-usage-limits 1.1.2 → 1.1.4

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.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.",
+  "version": "1.1.4",
+  "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:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-usage-limits",
-  "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.",
+  "version": "1.1.4",
+  "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:

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

@@ -43,10 +43,25 @@ function cacheFile() {
 // ever got a hit and both paid for a full scan each time.
 const KEEP_SESSIONS = 5;
 
+// A cache written before slots were keyed by session keeps its fields at the
+// top level, so upgrading would carry "at", "turnsLeft", "session" and
+// "sessionId" forward as if each were a session, crowding out real slots and
+// quietly undoing the per-session caching. Anything that is not a slot goes.
+function keepSlots(parsed) {
+  if (!parsed || typeof parsed !== 'object') return {};
+  const slots = {};
+  for (const key of Object.keys(parsed)) {
+    const value = parsed[key];
+    if (value && typeof value === 'object' && Number.isFinite(value.at)) {
+      slots[key] = value;
+    }
+  }
+  return slots;
+}
+
 function readCache() {
   try {
-    const parsed = JSON.parse(fs.readFileSync(cacheFile(), 'utf8'));
-    return parsed && typeof parsed === 'object' ? parsed : {};
+    return keepSlots(JSON.parse(fs.readFileSync(cacheFile(), 'utf8')));
   } catch (err) {
     return {};
   }
@@ -158,33 +173,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 ' +
@@ -193,7 +222,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) {
@@ -228,7 +264,8 @@ async function run(now, hookInput) {
   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
@@ -259,9 +296,11 @@ module.exports = {
   aheadOfPace,
   pressure,
   sessionSpend,
-  summarise,
+  describeWindow,
+  summariseOthers,
   briefText,
   settings,
+  keepSlots,
   pickCached,
   mergeCache,
   KEEP_SESSIONS,