claude-usage-limits 1.11.2 → 1.11.4

package/.claude-plugin/plugin.json

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

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "usage-limits",
-  "version": "1.11.2",
+  "version": "1.11.4",
   "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/README.md

@@ -347,6 +347,12 @@ every tool call keeps it so, the Stop hook marks it idle), so the list is live
 without anyone polling anything. The status line adds `+1 working` when
 another session is spending.
 
+Under the bars it says when the binding window runs out at the pace of the
+last hour, measured from every session's spend, whenever that comes before
+the reset: `at this pace the 5-hour window runs out in 25m, about 12 turns`,
+yellow inside half an hour and red inside ten minutes. The pane rings the
+terminal bell once when a window turns yellow and once more when it turns red.
+
 `panel` alone runs it in the current pane, `--once` prints one frame, `--json`
 prints the fields, `--no-fetch` (or `USAGE_LIMITS_FETCH=off`) keeps it
 entirely offline on the reading already on disk, and `--poll N` sets the
@@ -461,6 +467,7 @@ minute, so it costs about 400ms cold and 120ms warm.
 | `USAGE_LIMITS_CLOCK` | from settings | `12h` or `24h` for reset times; otherwise follows Claude Code's `timeFormat`. |
 | `USAGE_LIMITS_COLOUR` | detected | `256` or `none` to override colour detection. `NO_COLOR` and `FORCE_COLOR` are honoured. |
 | `USAGE_LIMITS_ASCII` | off | `1` draws the bars and the spinner with plain characters. |
+| `USAGE_LIMITS_BELL` | on | `off` silences the panel's terminal bell when a window turns yellow or red (`--no-bell` does the same). |
 
 ## What a session cost
 
@@ -666,12 +673,10 @@ allowance and never quotes a price, so the percentages stand alone. And
 
 The Claude Code extension for VS Code shows the limits only when you ask with
 `/usage`, and it does not render a custom status line. So there is an
-extension of its own in [vscode/](vscode/): the same bars as a view that sits
-directly under the Claude Code chat in the secondary side bar (it contributes
-into the Claude Code extension's own view container, so there is no gap and
-nothing to arrange), a status bar item with the percentages that turns yellow
-and red at the same thresholds, the Sessions list, and the same animations in
-CSS. It carries the plugin's scripts inside it, so it has no dependencies and
+extension of its own in [vscode/](vscode/): the same bars as one full-height
+view in the right sidebar, beside the chat, opened for you when VS Code
+starts, with the Sessions list and the same animations in CSS. Nothing at the
+bottom unless you turn `claudeUsageLimits.statusBar` on. It carries the plugin's scripts inside it, so it has no dependencies and
 reads the same files and takes the same reading as the terminal panel.
 
 ```
@@ -859,7 +864,7 @@ test/                             node --test, no dependencies
 node --test
 ```
 
-469 tests over the pricing, the window arithmetic, plan and credit detection,
+477 tests over the pricing, the window arithmetic, plan and credit detection,
 the status line, the before-prompt line, the mid-turn pulse, the after-reply tally and the session history, job forecasting,
 per-project attribution, the Codex reader and its installer, the CLI,
 packaging, and the settings save/restore.

package/package.json

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

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

@@ -47,6 +47,7 @@ const FILE_CHECK_MS = SECOND;
 const FRAME_MS = 100;
 const MIN_COLUMNS = 24;
 const TITLE = 'Claude usage';
+const LEVEL_RANK = { fill: 0, warning: 1, error: 2 };
 
 const HELP = `claude-usage-limits panel - live limits in a pane beside the chat
 
@@ -58,6 +59,7 @@ const HELP = `claude-usage-limits panel - live limits in a pane beside the chat
   panel --poll 45      seconds between readings (default 30 working, 120 idle)
   panel --width 40     draw for this many columns instead of the terminal's
   panel --ascii        plain characters instead of block glyphs
+  panel --no-bell      no terminal bell when a window turns yellow or red
 
 Shows the current session (5-hour) window, the current week, and the week for
 the model in use when the account caps that model on its own. Bars turn yellow
@@ -88,12 +90,14 @@ function parseArgs(argv) {
     width: null,
     help: false,
     ascii: String(process.env.USAGE_LIMITS_ASCII || '') === '1',
+    bell: true,
     hostName: null,
   };
   const list = argv || [];
   for (let i = 0; i < list.length; i += 1) {
     const arg = list[i];
     if (arg === '--once') args.once = true;
+    else if (arg === '--no-bell') args.bell = false;
     else if (arg === '--json') args.json = true;
     else if (arg === '--open') args.open = true;
     else if (arg === '--no-fetch') args.fetch = false;
@@ -182,6 +186,11 @@ async function snapshot(options) {
   built.sessionsList = onCodex ? [] : loadSessions(now);
   built.sessions = onCodex ? 0 : Math.max(built.sessionsList.length, brief.liveSessions(brief.readCache(), now, brief.LIVE_WINDOW_MS, null));
   built.othersWorking = built.sessionsList.filter((row) => row.state === 'working').length;
+  // What the pace says: when the binding window runs out at the current rate,
+  // if that comes before its reset. The transcript scan behind it belongs to
+  // the report, so it is taken with the readings, not with every frame; the
+  // frames in between carry the last answer forward.
+  built.pace = opts.pace !== undefined ? opts.pace : await paceOf(now);
   // Whether the panel is allowed the network at all, which is what the footer
   // reports. A frame rebuilt from disk between readings is not "network off".
   built.fetch = opts.network !== undefined ? Boolean(opts.network) : Boolean(opts.fetch);
@@ -189,6 +198,28 @@ async function snapshot(options) {
   return built;
 }
 
+// The report's runway: how long the binding window lasts at the pace of the
+// last hour, measured from every session's spend. The percentage says where
+// you are; this says when you hit the wall, which is the number the rival
+// monitors lead with and the one that matters on a busy afternoon.
+async function paceOf(now) {
+  try {
+    const data = await usage.report(now, {});
+    const binding = data && data.binding;
+    if (!binding || !Number.isFinite(binding.headroomMs)) return null;
+    const resetsInMs = Number.isFinite(binding.resetsAt) ? binding.resetsAt - now : null;
+    return {
+      label: binding.label,
+      headroomMs: binding.headroomMs,
+      resetsInMs,
+      turnsLeft: Number.isFinite(binding.turnsLeft) ? binding.turnsLeft : null,
+      runsOut: binding.verdict === 'runs-out' || (resetsInMs !== null && binding.headroomMs < resetsInMs),
+    };
+  } catch (err) {
+    return null;
+  }
+}
+
 // Codex has no hooks to say when it is working, but it appends to its rollout
 // file as it goes, so a rollout touched in the last few seconds is a turn in
 // progress.
@@ -252,6 +283,13 @@ function fit(text, width) {
   return out + '\x1b[0m';
 }
 
+// In a narrow pane the titles are the short ones.
+function shortTitle(row) {
+  if (row.key === 'five_hour') return 'Session';
+  if (row.key === 'seven_day') return 'Week';
+  return String(row.title).replace(/^Current week /, 'Week ').replace(/^Current /, '');
+}
+
 function subline(row, mode, opts) {
   if (row.stale) return bars.dim('window rolled over, taking a fresh reading', mode);
   if (row.unreported) return bars.dim('not reported yet, run /usage in Claude Code', mode);
@@ -336,7 +374,7 @@ function render(built, options) {
       row.level === 'fill' ? row.percentText : bars.paint(row.percentText, bars.levelColour(row.level), mode);
     body.push({
       lines: [
-        bars.bold(row.title, mode),
+        bars.bold(columns < 34 ? shortTitle(row) : row.title, mode),
         (row.percent === null ? bars.paint((ascii ? '-' : '░').repeat(barWidth), bars.THEME.empty, mode) : bars.bar(row.percent, barWidth, { mode, level: row.level, ascii })) +
           ' ' +
           percent,
@@ -382,6 +420,21 @@ function render(built, options) {
     const colour = noteColour(built);
     footer.push(colour ? bars.paint(built.note, colour, mode) : bars.dim(built.note, mode));
   }
+  if (built.pace && built.pace.runsOut && Number.isFinite(built.pace.headroomMs)) {
+    // The longest form that fits: a sentence in a wide pane, a phrase in a
+    // narrow one, never a sentence cut off halfway.
+    const left = usage.formatDuration(built.pace.headroomMs);
+    const turns = Number.isFinite(built.pace.turnsLeft) ? ', about ' + built.pace.turnsLeft + ' turns' : '';
+    const forms = [
+      'at this pace the ' + built.pace.label + ' window runs out in ' + left + turns,
+      'runs out in ' + left + ' at this pace' + turns,
+      'runs out in ' + left + ' at this pace',
+      'wall in ' + left,
+    ];
+    const text = forms.find((form) => form.length <= real) || forms[forms.length - 1];
+    const colour = built.pace.headroomMs < 10 * MINUTE ? bars.THEME.error : built.pace.headroomMs < 30 * MINUTE ? bars.THEME.warning : null;
+    footer.push(colour ? bars.paint(text, colour, mode) : bars.dim(text, mode));
+  }
   footer.push(stateLine(built, mode));
   if (opts.interactive !== false) footer.push(bars.dim('q quit · r refresh', mode));
 
@@ -425,21 +478,21 @@ function openCommand(env, panelPath, nodePath, platform, extraArgs, options) {
     const old = version && (Number(version[1]) < 3 || (Number(version[1]) === 3 && Number(version[2]) < 1));
     return {
       program: 'tmux',
-      args: ['split-window', '-h', '-d'].concat(old ? ['-p', '32'] : ['-l', '32%'], [cmd]),
+      args: ['split-window', '-h', '-d'].concat(old ? ['-p', '24'] : ['-l', '24%'], [cmd]),
       note: 'opened a pane to the right in tmux',
     };
   }
   if (e.WEZTERM_PANE) {
     return {
       program: 'wezterm',
-      args: ['cli', 'split-pane', '--right', '--percent', '32', '--', node, panel].concat(extra),
+      args: ['cli', 'split-pane', '--right', '--percent', '24', '--', node, panel].concat(extra),
       note: 'opened a pane to the right in WezTerm',
     };
   }
   if (e.KITTY_WINDOW_ID) {
     return {
       program: 'kitten',
-      args: ['@', 'launch', '--location=vsplit', '--bias=32', '--cwd=current', node, panel].concat(extra),
+      args: ['@', 'launch', '--location=vsplit', '--bias=24', '--cwd=current', node, panel].concat(extra),
       note: 'opened a pane to the right in kitty (needs allow_remote_control)',
     };
   }
@@ -454,7 +507,7 @@ function openCommand(env, panelPath, nodePath, platform, extraArgs, options) {
     if (e.WT_SESSION) {
       return {
         command:
-          'start "" wt.exe -w 0 sp -V --size 0.32 --title "Claude usage" --suppressApplicationTitle ' + cmd,
+          'start "" wt.exe -w 0 sp -V --size 0.24 --title "Claude usage" --suppressApplicationTitle ' + cmd,
         shell: true,
         note: 'opened a pane to the right in Windows Terminal',
       };
@@ -539,8 +592,10 @@ async function interactive(args) {
   const clock = feed.clockFor(settings, env);
   const mode = bars.colourMode(env, out.isTTY);
   const fetch = args.fetch && !live.fetchDisabled(env);
+  const bell = args.bell && String(env.USAGE_LIMITS_BELL || '').toLowerCase() !== 'off';
 
   const state = {
+    levels: {},
     built: null,
     outcome: null,
     lastFetchAt: 0,
@@ -643,10 +698,25 @@ async function interactive(args) {
     if (!state.built || now - state.lastCheck >= FILE_CHECK_MS) {
       state.lastCheck = now;
       try {
-        state.built = await snapshot({ fetch: false, network: fetch, env, now, outcome: state.outcome });
+        state.built = await snapshot({
+          fetch: false,
+          network: fetch,
+          env,
+          now,
+          outcome: state.outcome,
+          pace: state.built ? state.built.pace : null,
+        });
       } catch (err) {
         // Keep the last frame; a transient read error is not worth a blank.
       }
+      // One bell when a window first turns yellow, another when it turns red.
+      if (bell && state.built) {
+        for (const row of state.built.rows) {
+          const before = state.levels[row.key];
+          if (before !== undefined && LEVEL_RANK[row.level] > LEVEL_RANK[before]) out.write('\x07');
+          state.levels[row.key] = row.level;
+        }
+      }
       // A window that rolled over deserves a reading sooner than the timer.
       if (fetch && state.built && state.built.rows.some((row) => row.stale) && state.delayMs > 5 * SECOND) {
         state.delayMs = 5 * SECOND;