claude-usage-limits 1.14.1 → 1.16.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usage-limits",
   "displayName": "Usage Limits",
-  "version": "1.14.1",
+  "version": "1.16.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/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "usage-limits",
-  "version": "1.14.1",
+  "version": "1.16.0",
   "description": "Reports how much of your Codex usage limit is left as turns of work rather than a percentage, prices a job before you start it, and counts the other agents sharing the same budget.",
   "author": {
     "name": "Ridelink",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-usage-limits",
-  "version": "1.14.1",
+  "version": "1.16.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/SKILL.md

@@ -387,6 +387,23 @@ is. There are two, and only one of them is the account's budget.
   this account. `node scripts/usage.js --recommend` names both levers with the
   commands.
 
+**The commands differ by host, and the wrong one does nothing.** `/model` and
+`/effort` do not exist in Codex. Under Codex, change the model and effort for
+the task in hand through Codex's own controls; `node scripts/lowpower.js on
+--host codex --effort low --model <id>` only saves defaults for *new* sessions
+and cannot change one already running. The budget line prints whichever
+vocabulary the host it is running in actually understands, so use the command
+it gives you rather than the one you remember.
+
+**This is a lever you may pull yourself, not only an emergency exit.** Use it
+whenever the current setting is dearer than the work in front of you needs,
+without being asked and long before any window is tight: a mechanical rename,
+a docs pass or a mass find-and-replace does not need the model and effort a
+hard design decision does. Drop it for that stretch, say in one line that you
+did and why, and put it back when the work gets hard again. An agent that only
+ever reads this as a wall notice runs every trivial turn at the top setting and
+then wonders where the window went.
+
 The budget line does this arithmetic for you. Once the binding window is half
 gone it says which lever applies, and at the wall it says outright that you are
 not out of budget and must not stop as though you were. When it does, the

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

@@ -548,7 +548,13 @@ function briefText(parts) {
       sentences.push(
         'The effort setting is what is spending this: ' + bits.join(', and ') +
           '. Keep it where the work genuinely needs the thinking and drop it where it ' +
-          'does not; it changes what every turn costs, not how many you get.'
+          'does not; it changes what every turn costs, not how many you get.' +
+          // The command, in the host's own vocabulary. /effort does not exist
+          // in Codex, and naming it there is telling Codex to do nothing while
+          // believing it acted.
+          (warning.cheaper && warning.cheaper.effort
+            ? ' To drop it: ' + usage.levers(usage.currentHost()).effort(warning.cheaper.effort) + '.'
+            : '')
       );
     }
   }
@@ -580,14 +586,27 @@ function briefText(parts) {
         (escape.nextLabel
           ? 'After a switch the binding window would be ' + escape.nextLabel + ' at ' + escape.nextPercent + ' per cent. '
           : '') +
-        'Use /model ' + (escape.suggest || '<another model>') + ' (or scripts/lowpower.js on --model <id>).'
+        // No command rather than a wrong one: the vocabulary differs by host,
+        // and "Use undefined" is worse than saying which lever it is and
+        // leaving the reader to reach for it.
+        (escape.command ? 'Use ' + escape.command + '.' : '')
       : escape && escape.kind === 'effort'
         ? 'A model switch does not free this window - it follows the account - but effort does: ' +
           escape.to + ' measured ' + (escape.multiple ? escape.multiple + 'x ' : '') + 'cheaper a turn than ' +
-          (escape.from || 'the current effort') + '. Use /effort ' + escape.to + '.'
+          (escape.from || 'the current effort') + '.' + (escape.command ? ' Use ' + escape.command + '.' : '')
         : null;
+  // Not only an emergency exit. The same lever is the right one whenever the
+  // setting is dearer than the work in front of you needs - a mechanical edit
+  // does not need the model a hard design decision does. Say so, because an
+  // agent that only ever reads this as a wall notice will run every trivial
+  // turn at the top setting and then wonder where the window went.
+  const chooseText = escapeText
+    ? ' You may make that change yourself, at any point and without being asked, ' +
+      'whenever the current setting is dearer than the work needs rather than only ' +
+      'when the window is nearly gone. Say in one line that you changed it and why.'
+    : '';
   if (escapeText && parts.binding && Number.isFinite(parts.binding.percentUsed) && parts.binding.percentUsed >= HALF_SPENT) {
-    sentences.push(escapeText);
+    sentences.push(escapeText + chooseText);
   }
 
   // A window that is not binding can still be the expensive one to exhaust.
@@ -955,7 +974,7 @@ async function run(now, hookInput) {
       othersSummary: summariseOthers(data.windows, binding && binding.key),
       // The way out that is not stopping. Cached with the rest of the view
       // because it is derived from the same one pass over the windows.
-      escape: usage.escapeRoute(data.windows, binding, data.effortWarning || null),
+      escape: usage.escapeRoute(data.windows, binding, data.effortWarning || null, usage.currentHost()),
       // Every window, trimmed to the cacheable fields, so the corrected reading
       // can be recorded for all three columns of the status line on a cache
       // hit too. Recording the binding window alone left the other two at

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

@@ -238,10 +238,25 @@ function line(built, options) {
     Number.isFinite(built.othersWorking) && built.othersWorking > 0
       ? bars.paint('+' + built.othersWorking + ' working', bars.THEME.claude, mode)
       : '';
+  // Agents spend the same window and were the one thing on it with no voice.
+  // A fan-out can empty half a five-hour window in five minutes while the line
+  // shows one session working, so the count goes on the line whenever any are
+  // live - and it is dropped first when the terminal is too narrow, because a
+  // percentage the user cannot see is worse than a count they cannot see.
+  const agents =
+    built.agents && built.agents.running > 0
+      ? bars.paint(
+          '+' + built.agents.running + ' agent' + (built.agents.running === 1 ? '' : 's') +
+            (built.agents.runs > 1 ? ' (' + built.agents.runs + ' runs)' : ''),
+          bars.THEME.claude,
+          mode
+        )
+      : '';
   let text = '';
   for (const attempt of attempts) {
     const parts = built.rows.map((row) => segment(row, attempt.width, attempt.shorter));
     if (others) parts.push(others);
+    if (agents && !attempt.shorter) parts.push(agents);
     if (attempt.head) parts.unshift(head);
     text = parts.join(attempt.gap || '  ');
     if (bars.visibleWidth(text) <= columns) return text;
@@ -445,6 +460,7 @@ async function main(argv) {
       .filter((row) => row.state === 'working' && row.sessionId !== mine).length;
     const built = view.build({
       now,
+      agents: usage.liveAgents(now),
       utilization: collected.utilization,
       fetchedAtMs: collected.snapshotFetchedAt,
       source: collected.snapshotSource,

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

@@ -534,6 +534,75 @@ function subagentTranscripts(dir, since, depth) {
   return files;
 }
 
+// The agents working right now, and what they have cost.
+//
+// Their spend has always been counted - the scan walks subagents/ and
+// workflows/ and every token lands in the window totals - but nothing ever
+// SHOWED them. So a display could say one session was working while eighteen
+// agents underneath it spent two million tokens, and the only sign was the
+// percentage moving for no visible reason. One workflow in this plugin's own
+// development did exactly that twice in an afternoon.
+//
+// Cheap on purpose: it stats files under the session's own subagent
+// directories and never parses one. The panel redraws every second.
+const AGENT_LIVE_MS = 90 * 1000;
+
+// Measured at about 95 ms on a machine with a few hundred agent transcripts.
+// The panel redraws every second, so without this it would spend a tenth of
+// every frame stat-ing files that cannot have changed much.
+let agentMemo = null;
+const AGENT_MEMO_MS = 2000;
+
+function liveAgents(now, windowMs) {
+  const at = Number.isFinite(now) ? now : Date.now();
+  const within = Number.isFinite(windowMs) ? windowMs : AGENT_LIVE_MS;
+  if (agentMemo && agentMemo.within === within && at - agentMemo.at < AGENT_MEMO_MS) return agentMemo.value;
+  const root = path.join(configDir(), 'projects');
+  let projects = [];
+  try {
+    projects = fs.readdirSync(root, { withFileTypes: true });
+  } catch (err) {
+    return { running: 0, runs: 0, newestAt: null };
+  }
+  let running = 0;
+  const runs = new Set();
+  // projects/<project>/<sessionId>/subagents/[workflows/<run>/]agent-*.jsonl -
+  // the session id is a level the first version of this walked straight past,
+  // which is why it counted nothing on a machine with a hundred and fifty
+  // agent transcripts an hour old.
+  for (const project of projects) {
+    if (!project.isDirectory()) continue;
+    let sessions = [];
+    try {
+      sessions = fs.readdirSync(path.join(root, project.name), { withFileTypes: true });
+    } catch (err) {
+      continue;
+    }
+    for (const session of sessions) {
+      if (!session.isDirectory()) continue;
+      const dir = path.join(root, project.name, session.name, 'subagents');
+      for (const file of subagentTranscripts(dir, at - within, 3)) {
+        let stat;
+        try {
+          stat = fs.statSync(file);
+        } catch (err) {
+          continue;
+        }
+        if (at - stat.mtimeMs > within) continue;
+        running += 1;
+        // .../workflows/<run>/agent-x.jsonl - the run is what a person
+        // recognises, so it is counted as well as the agents. An agent that is
+        // not in a workflow sits directly in subagents/ and is its own run.
+        const parent = path.basename(path.dirname(file));
+        runs.add(parent === 'subagents' ? 'agent:' + path.basename(file) : parent);
+      }
+    }
+  }
+  const value = { running, runs: runs.size, newestAt: running ? at : null };
+  agentMemo = { at, within, value };
+  return value;
+}
+
 function claudeTranscriptFiles(since) {
   const root = path.join(configDir(), 'projects');
   let dirs = [];
@@ -2104,8 +2173,32 @@ function criticalOthers(windows, bindingKey, threshold) {
 // changes nothing and the lever is effort instead. Either way the point is the
 // same - being at the wall is not the same as being out of budget, and an agent
 // that cannot tell the difference stops early and calls it caution.
-function escapeRoute(windows, binding, effortNote) {
+// The commands differ by host and getting them wrong is worse than saying
+// nothing: /model and /effort do not exist in Codex, and telling Codex to run
+// them is telling it to do nothing while believing it acted. Codex changes its
+// own model and effort through its own controls; the script can only save
+// defaults for NEW sessions, which is a different promise and is stated as one.
+function levers(which) {
+  // `host` is the required module here, not a parameter - shadowing it was a
+  // ReferenceError on the constant it owns.
+  const codex = which === host.CODEX;
+  return {
+    model: (family) =>
+      codex
+        ? "Codex's own model control (the script only saves defaults for new sessions: " +
+          'node scripts/lowpower.js on --host codex --model <id>)'
+        : '/model ' + (family || '<another model>') + ' (or node scripts/lowpower.js on --model <id>)',
+    effort: (level) =>
+      codex
+        ? "Codex's own effort control for this task (node scripts/lowpower.js on --host codex --effort " +
+          (level || '<level>') + ' saves it for new sessions and cannot change one already running)'
+        : '/effort ' + (level || '<level>'),
+  };
+}
+
+function escapeRoute(windows, binding, effortNote, host) {
   if (!binding || binding.percentUsed === null || binding.percentUsed === undefined) return null;
+  const lever = levers(host || currentHost());
   const live = (windows || []).filter(
     (w) => w && w.percentUsed !== null && w.percentUsed !== undefined && !w.stale && w.key !== binding.key
   );
@@ -2133,6 +2226,7 @@ function escapeRoute(windows, binding, effortNote) {
       nextLabel: next ? next.label || next.key : null,
       nextPercent: next ? Math.round(next.percentUsed) : null,
       suggest: roomier && roomier.family ? roomier.family : null,
+      command: lever.model(roomier && roomier.family ? roomier.family : null),
     };
   }
 
@@ -2144,6 +2238,7 @@ function escapeRoute(windows, binding, effortNote) {
       from: effortNote.effort || null,
       to: effortNote.cheaper.effort,
       multiple: Number.isFinite(effortNote.cheaper.multiple) ? effortNote.cheaper.multiple : null,
+      command: lever.effort(effortNote.cheaper.effort),
     };
   }
   return null;
@@ -3688,6 +3783,8 @@ module.exports = {
   preferLive,
   accountUuid,
   subagentTranscripts,
+  liveAgents,
+  AGENT_LIVE_MS,
   claudeTranscriptFiles,
   readClaudeEvents,
   SCAN_VERSION,
@@ -3740,6 +3837,7 @@ module.exports = {
   bindingWindow,
   criticalOthers,
   escapeRoute,
+  levers,
   betterCalibration,
   calibrationForPlan,
   stampPlan,

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

@@ -352,6 +352,9 @@ function build(input) {
     rows,
     fable,
     hidden,
+    // The agents underneath this session. They spend the same window and had
+    // no voice on any display until now.
+    agents: opts.agents && Number.isFinite(opts.agents.running) ? opts.agents : { running: 0, runs: 0 },
     model,
     modelLabel: opts.modelName || bars.prettyModel(model),
     effort,