claude-usage-limits 1.19.0 → 1.24.0

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

@@ -0,0 +1,318 @@
+#!/usr/bin/env node
+'use strict';
+
+// "Not now. Do it at ten."
+//
+// The relay answers a question the plugin asks itself: the window ran out, so
+// when can this be picked up? This answers a question the USER asks: I do not
+// want this started now, start it then.
+//
+// They share all the machinery below the surface - the same saved plan, the
+// same scheduled task, the same wake script - and differ in one way that
+// matters. The relay fires when a window RESETS, which is a time nobody chose
+// and which moves. A deferral fires at a time a person named, so the grace
+// minutes that let a meter settle are not added to it: 9:50 means 9:50.
+//
+//   node defer.js 9:50pm                 tonight at 21:50
+//   node defer.js 21:50 --work "..."     with the work spelled out
+//   node defer.js "in 90m"               ninety minutes from now
+//   node defer.js reset                  when the binding window resets
+//   node defer.js status                 what is deferred, and when it fires
+//   node defer.js cancel                 call it off
+//
+// The reply is deliberately one line. The whole point of the command is that
+// nothing happens now, and a paragraph explaining that would itself be the
+// thing the user was trying to avoid.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const relay = require('./relay.js');
+const host = require('./host.js');
+
+const MINUTE = 60 * 1000;
+const HOUR = 60 * MINUTE;
+
+// ---------------------------------------------------------------------------
+// When
+// ---------------------------------------------------------------------------
+
+// Turn what somebody typed into a moment.
+//
+// Deliberately narrow. Every format here is one a person actually types at a
+// terminal, and anything else is refused with the list rather than guessed at:
+// a deferral that silently fires at the wrong hour is worse than one that
+// refuses to be set.
+function parseWhen(text, now, resetsAt) {
+  const raw = String(text == null ? '' : text).trim().toLowerCase();
+  if (!raw) return { error: 'No time given.' };
+
+  // The window reset, which is the common case and the sensible default.
+  if (/^(reset|next reset|the reset|window|when it resets)$/.test(raw)) {
+    if (!Number.isFinite(resetsAt)) {
+      return { error: 'The reset time is not known right now, so name a clock time instead.' };
+    }
+    // The one case where the relay's grace IS wanted: a meter needs a moment
+    // to turn over, and this is a window reset rather than a chosen time.
+    return { at: resetsAt + 5 * MINUTE, label: 'when the window resets' };
+  }
+
+  // "in 90m", "in 2h", "in 45 minutes", "in 1.5 hours"
+  const relative = raw.match(/^in\s+([0-9]+(?:\.[0-9]+)?)\s*(m|min|mins|minute|minutes|h|hr|hrs|hour|hours)$/);
+  if (relative) {
+    const amount = Number(relative[1]);
+    if (!Number.isFinite(amount) || amount <= 0) return { error: 'That is not a length of time.' };
+    const unit = /^m/.test(relative[2]) ? MINUTE : HOUR;
+    const span = amount * unit;
+    // A year out is not a deferral, it is a mistake.
+    if (span > 14 * 24 * HOUR) return { error: 'That is more than a fortnight away.' };
+    return { at: now + span, label: 'in ' + relative[1] + (unit === MINUTE ? ' minutes' : ' hours') };
+  }
+
+  // "9:50pm", "9pm", "21:50", "09:50"
+  const clock = raw.match(/^([0-9]{1,2})(?::([0-9]{2}))?\s*(am|pm)?$/);
+  if (clock) {
+    let hour = Number(clock[1]);
+    const minute = clock[2] === undefined ? 0 : Number(clock[2]);
+    const meridiem = clock[3];
+    if (minute > 59) return { error: 'There is no such minute as ' + minute + '.' };
+    if (meridiem) {
+      if (hour < 1 || hour > 12) return { error: 'With am or pm the hour has to be 1 to 12.' };
+      if (meridiem === 'pm' && hour !== 12) hour += 12;
+      if (meridiem === 'am' && hour === 12) hour = 0;
+    } else if (hour > 23) {
+      return { error: 'There is no such hour as ' + hour + '.' };
+    } else if (clock[2] === undefined) {
+      // A bare number with no minutes and no am/pm is ambiguous - "9" could be
+      // either nine. Refuse rather than pick one.
+      return { error: 'Ambiguous: say 9am, 9pm or 09:00.' };
+    }
+    const at = new Date(now);
+    at.setHours(hour, minute, 0, 0);
+    let stamp = at.getTime();
+    // A time already past today means tomorrow. That is what a person means by
+    // "do it at nine" when they say it at eleven at night.
+    if (stamp <= now) stamp += 24 * HOUR;
+    return { at: stamp, label: formatClock(stamp) };
+  }
+
+  return {
+    error:
+      'Could not read "' + text + '" as a time. Try 9:50pm, 21:50, "in 90m", or "reset".',
+  };
+}
+
+function formatClock(stamp) {
+  const d = new Date(stamp);
+  let hour = d.getHours();
+  const meridiem = hour >= 12 ? 'PM' : 'AM';
+  hour = hour % 12 === 0 ? 12 : hour % 12;
+  const minute = String(d.getMinutes()).padStart(2, '0');
+  return hour + ':' + minute + ' ' + meridiem;
+}
+
+// "3h 12m", the same shape the rest of the plugin prints.
+function formatSpan(ms) {
+  if (!Number.isFinite(ms) || ms <= 0) return 'now';
+  const minutes = Math.round(ms / MINUTE);
+  if (minutes < 60) return minutes + 'm';
+  const hours = Math.floor(minutes / 60);
+  const rest = minutes % 60;
+  if (hours < 24) return rest ? hours + 'h ' + rest + 'm' : hours + 'h';
+  const days = Math.floor(hours / 24);
+  return days + 'd ' + (hours % 24) + 'h';
+}
+
+// ---------------------------------------------------------------------------
+// The line
+// ---------------------------------------------------------------------------
+
+// One sentence, and it has to carry four things: that nothing was started,
+// when it will start, how far away that is, and how to call it off. Everything
+// else is noise in a command whose whole purpose is to not do things.
+function confirmation(parts) {
+  const bits = [];
+  const descriptive = parts.label && parts.label !== parts.clock && !/^in /.test(parts.label);
+  bits.push('Doing this at ' + parts.clock + (descriptive ? ' (' + parts.label + ')' : ''));
+  bits.push('in ' + formatSpan(parts.in));
+  const line = bits.join(', ') + '. ';
+  const tail = [];
+  tail.push('Nothing has been started');
+  if (parts.items) tail.push(parts.items + ' saved');
+  if (parts.resetNote) tail.push(parts.resetNote);
+  return line + tail.join('; ') + '. Run "defer cancel" to call it off.';
+}
+
+// ---------------------------------------------------------------------------
+// Doing it
+// ---------------------------------------------------------------------------
+
+function bindingReset(now) {
+  try {
+    const usage = require('./usage.js');
+    usage.setHost(host.detect(process.argv.slice(2), process.env));
+    const collected = usage.collect(now);
+    const utilization = collected && collected.utilization;
+    if (!utilization) return { resetsAt: null, percent: null };
+    let worst = null;
+    for (const key of Object.keys(utilization)) {
+      const window = utilization[key];
+      if (!window || typeof window !== 'object') continue;
+      const percent = Number(window.utilization);
+      if (!Number.isFinite(percent)) continue;
+      const resets = Date.parse(window.resets_at);
+      if (!worst || percent > worst.percent) {
+        worst = { percent, resetsAt: Number.isFinite(resets) ? resets : null };
+      }
+    }
+    return worst || { resetsAt: null, percent: null };
+  } catch (err) {
+    return { resetsAt: null, percent: null };
+  }
+}
+
+function sessionId(argv, env) {
+  const at = argv.indexOf('--session-id');
+  if (at !== -1 && argv[at + 1]) return argv[at + 1];
+  return env.CLAUDE_SESSION_ID || env.CODEX_SESSION_ID || 'defer-' + Date.now().toString(36);
+}
+
+function argOf(argv, name) {
+  const at = argv.indexOf(name);
+  return at === -1 ? null : argv[at + 1] || null;
+}
+
+function plan(options) {
+  const now = options.now;
+  const binding = options.binding || { resetsAt: null, percent: null };
+  const when = parseWhen(options.when, now, binding.resetsAt);
+  if (when.error) return { ok: false, error: when.error };
+
+  const notes = [];
+  // Worth saying, because it is the difference between the deferred run having
+  // a budget and hitting the same wall again.
+  if (Number.isFinite(binding.resetsAt)) {
+    if (when.at >= binding.resetsAt) notes.push('the window will have reset by then');
+    else if (Number.isFinite(binding.percent) && binding.percent >= 80) {
+      notes.push('note: that is before the window resets at ' + formatClock(binding.resetsAt));
+    }
+  }
+  return {
+    ok: true,
+    at: when.at,
+    label: when.label,
+    clock: formatClock(when.at),
+    in: when.at - now,
+    resetNote: notes[0] || null,
+  };
+}
+
+function status(now) {
+  const state = relay.read();
+  const armed = state.armed;
+  if (!armed) return 'Nothing is deferred.';
+  const when = Number(armed.wakeAt);
+  const deferred = armed.deferred === true;
+  return (
+    (deferred ? 'Deferred' : 'Relay armed') +
+    ': ' +
+    (armed.project || path.basename(armed.cwd || '')) +
+    ' at ' +
+    formatClock(when) +
+    ' (in ' +
+    formatSpan(when - now) +
+    ')' +
+    (armed.how ? ', via ' + armed.how : '') +
+    '.'
+  );
+}
+
+function cancel() {
+  const state = relay.read();
+  if (!state.armed) return 'Nothing was deferred.';
+  const label = formatClock(Number(state.armed.wakeAt));
+  const result = relay.disarm('cancelled by hand', Date.now());
+  return result && result.ok === false
+    ? 'Could not cancel: ' + result.error
+    : 'Cancelled the run booked for ' + label + '.';
+}
+
+function main(argv, now) {
+  const args = (argv || []).filter((a) => a !== undefined);
+  const first = args.find((a) => !a.startsWith('--')) || '';
+  const at = Number.isFinite(now) ? now : Date.now();
+
+  if (first === 'status') return status(at);
+  if (first === 'cancel' || first === 'off') return cancel();
+  if (!first || first === 'help') {
+    return [
+      'defer <time> [--work "..."]   put the work off until then and start nothing now',
+      '  9:50pm | 21:50 | "in 90m" | reset',
+      'defer status                  what is deferred and when it fires',
+      'defer cancel                  call it off',
+    ].join('\n');
+  }
+
+  const binding = bindingReset(at);
+  const decided = plan({ now: at, when: first, binding });
+  if (!decided.ok) return decided.error;
+
+  const id = sessionId(args, process.env);
+  const work = argOf(args, '--work');
+  const cwd = argOf(args, '--cwd') || process.cwd();
+
+  // The plan is saved before the task is registered. A task that fires with
+  // nothing to read is worse than a plan nobody scheduled.
+  let items = null;
+  if (work) {
+    relay.saveContinuation(id, work);
+    items = work.split('\n').filter((l) => l.trim()).length + ' line' +
+      (work.split('\n').filter((l) => l.trim()).length === 1 ? '' : 's');
+  }
+
+  const armed = relay.arm({
+    now: at,
+    sessionId: id,
+    cwd,
+    hostName: host.detect(args, process.env),
+    at: decided.at,
+    binding: { percentUsed: binding.percent, resetsAt: binding.resetsAt },
+    work: { hasWork: true, pending: 1, source: 'defer', todos: [] },
+  });
+  if (!armed.ok) return 'Could not schedule it: ' + armed.error;
+
+  // Mark it as a deferral rather than a limit relay, so `status` and the next
+  // session can tell the two apart - they read the same record.
+  try {
+    const held = relay.read();
+    if (held.armed) {
+      held.armed.deferred = true;
+      held.armed.continuation = Boolean(work);
+      relay.write(held);
+    }
+  } catch (err) {
+    // The schedule is the part that matters; the label is not worth failing for.
+  }
+
+  relay.note('deferred ' + id + ' until ' + new Date(decided.at).toISOString(), at);
+  return confirmation({
+    label: decided.label,
+    clock: decided.clock,
+    in: decided.in,
+    items,
+    resetNote: decided.resetNote,
+  });
+}
+
+if (require.main === module) {
+  try {
+    process.stdout.write(main(process.argv.slice(2), Date.now()) + '\n');
+    process.exitCode = 0;
+  } catch (err) {
+    process.stderr.write('defer: ' + (err && err.message ? err.message : String(err)) + '\n');
+    process.exitCode = 1;
+  }
+}
+
+module.exports = { parseWhen, formatClock, formatSpan, confirmation, plan, status, cancel, main, MINUTE, HOUR };

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

@@ -0,0 +1,254 @@
+'use strict';
+
+// A ledger of how wrong the reading was, measured instead of argued about.
+//
+// The known complaint about this plugin is that its numbers lag reality
+// mid-session - reading.js exists because of one measured instance of it (13%
+// shown, 73% actual). But "it lags" is an anecdote until someone can say by
+// how much, how often, and whether it is getting better or worse as the
+// plugin changes. So every time reading.js records a fresh, trustworthy
+// correction for a window, and there was already a figure sitting there for
+// readers to trust, this writes down what that older figure said next to what
+// the new one says. The gap between them is the drift a real session lived
+// through between two corrections.
+//
+// Same constraints as reading.js: cheap, bounded, and it must never be the
+// reason a hook is late or fails.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const host = require('./host.js');
+const codex = require('./codex.js');
+
+// Not "how many windows" but "how many measurements": a busy day produces a
+// handful of corrections per window, and a fixed cap keeps the file the same
+// size whether the plugin has run for a day or a year.
+const MAX_ENTRIES = 200;
+
+function configDir() {
+  return process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+}
+
+function driftFile(codexHome) {
+  return path.join(codexHome || configDir(), 'usage-limits-drift.json');
+}
+
+// The other measurement that belongs here: what a turn actually cost while
+// each budget mode was on. Same file, same bounded append, for the same
+// reason - it is an after-the-fact measurement of a prediction, and a second
+// store would be a second thing to keep correct. Modes should be evidence
+// rather than vibes, and this is where the evidence lands.
+const MAX_MODE_ENTRIES = 400;
+
+function read(codexHome) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(driftFile(codexHome), 'utf8'));
+    if (!parsed || typeof parsed !== 'object') return { entries: [] };
+    const state = { entries: Array.isArray(parsed.entries) ? parsed.entries : [] };
+    // The mode ledger is carried only when the file actually has one. A reader
+    // that has never recorded a mode gets back exactly the shape it wrote, so
+    // adding this second ledger did not change what the first one reads.
+    if (Array.isArray(parsed.modes)) state.modes = parsed.modes;
+    return state;
+  } catch (err) {
+    return { entries: [] };
+  }
+}
+
+// One reply, priced, tagged with the mode that was in force while it ran.
+// Called from the Stop hook, which already has the exact figures.
+function recordTurns(mode, turns, cost, now, codexHome) {
+  if (!mode || !Number.isFinite(turns) || turns <= 0) return false;
+  try {
+    const state = read(codexHome);
+    if (!Array.isArray(state.modes)) state.modes = [];
+    state.modes.push({
+      mode: String(mode),
+      at: Number.isFinite(now) ? now : Date.now(),
+      turns,
+      cost: Number.isFinite(cost) ? cost : 0,
+    });
+    if (state.modes.length > MAX_MODE_ENTRIES) state.modes = state.modes.slice(-MAX_MODE_ENTRIES);
+    writeAtomic(driftFile(codexHome), state);
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+// Turns and observed cost per turn, per mode. Only what was measured: a mode
+// nothing has run in is absent rather than shown at zero, because a zero here
+// reads as "free" when it means "unknown".
+function modeSummary(codexHome) {
+  const rows = {};
+  for (const entry of read(codexHome).modes || []) {
+    if (!entry || !entry.mode || !Number.isFinite(entry.turns)) continue;
+    const row = rows[entry.mode] || (rows[entry.mode] = { mode: entry.mode, turns: 0, usd: 0 });
+    row.turns += entry.turns;
+    row.usd += Number.isFinite(entry.cost) ? entry.cost : 0;
+  }
+  return Object.keys(rows)
+    .map((key) => {
+      const row = rows[key];
+      return {
+        mode: row.mode,
+        turns: row.turns,
+        usd: row.usd,
+        usdPerTurn: row.turns > 0 && row.usd > 0 ? row.usd / row.turns : null,
+      };
+    })
+    .sort((a, b) => b.turns - a.turns);
+}
+
+function writeAtomic(file, data) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  // Same beside-and-rename as reading.js: the pulse and the prompt hook can
+  // both land here in the same second.
+  const tmp = file + '.' + process.pid + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(data));
+  fs.renameSync(tmp, file);
+}
+
+// `previous` and `next` are both entries in reading.js's own shape - see
+// reading.record(). Called from there, right before it overwrites the slot,
+// so `previous` is what readers were trusting and `next` is what the fresh
+// scan just found for the same window.
+function record(key, previous, next, now, codexHome) {
+  if (!key || !previous || !next) return false;
+  if (!Number.isFinite(previous.percentUsed) || !Number.isFinite(next.percentUsed)) return false;
+  if (!Number.isFinite(previous.at)) return false;
+  const at = Number.isFinite(now) ? now : Date.now();
+  // A window that reset between the two readings did not "drift" - it started
+  // over, and treating the jump as error would swamp every real measurement.
+  if (Number.isFinite(previous.resetsAt) && previous.resetsAt <= next.at) return false;
+  try {
+    const state = read(codexHome);
+    state.entries.push({
+      key,
+      at,
+      // How long the older figure had been sitting in front of readers before
+      // this measurement replaced it - a drift found after two minutes and
+      // one found after twenty are not the same kind of evidence.
+      ageMs: Math.max(0, next.at - previous.at),
+      predictedPercentUsed: previous.percentUsed,
+      actualPercentUsed: next.percentUsed,
+      percentDrift: next.percentUsed - previous.percentUsed,
+      predictedTurnsLeft: Number.isFinite(previous.turnsLeft) ? previous.turnsLeft : null,
+      actualTurnsLeft: Number.isFinite(next.turnsLeft) ? next.turnsLeft : null,
+    });
+    if (state.entries.length > MAX_ENTRIES) state.entries = state.entries.slice(-MAX_ENTRIES);
+    writeAtomic(driftFile(codexHome), state);
+    return true;
+  } catch (err) {
+    return false;
+  }
+}
+
+function median(values) {
+  if (!values.length) return null;
+  const sorted = values.slice().sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+// What the ledger has actually shown: the typical gap and the worst one, in
+// percentage points, over whatever window filter is asked for (default:
+// everything on record). Turns get the same treatment where both sides of a
+// pair have a turns figure to compare.
+function summary(codexHome, options) {
+  const opts = options || {};
+  const state = read(codexHome);
+  let entries = state.entries;
+  if (opts.key) entries = entries.filter((e) => e.key === opts.key);
+  if (!entries.length) return { sample: 0, medianAbsPercent: null, worstAbsPercent: null, medianAbsTurns: null, worstAbsTurns: null };
+
+  const percentAbs = entries.map((e) => Math.abs(e.percentDrift));
+  const turnsAbs = entries
+    .filter((e) => Number.isFinite(e.predictedTurnsLeft) && Number.isFinite(e.actualTurnsLeft))
+    .map((e) => Math.abs(e.actualTurnsLeft - e.predictedTurnsLeft));
+
+  // A number of points on its own says nothing: sixty points off is a scandal
+  // over two minutes and unremarkable over five hours. The gap the figure was
+  // wrong for is what makes it readable, and it is already on every entry.
+  const ages = entries.map((e) => e.ageMs).filter((ms) => Number.isFinite(ms));
+  const worst = entries.reduce(
+    (found, e) => (!found || Math.abs(e.percentDrift) > Math.abs(found.percentDrift) ? e : found),
+    null
+  );
+
+  return {
+    sample: entries.length,
+    medianAbsPercent: median(percentAbs),
+    worstAbsPercent: percentAbs.length ? Math.max(...percentAbs) : null,
+    medianAbsTurns: turnsAbs.length ? median(turnsAbs) : null,
+    worstAbsTurns: turnsAbs.length ? Math.max(...turnsAbs) : null,
+    medianGapMs: ages.length ? median(ages) : null,
+    worstGapMs: worst && Number.isFinite(worst.ageMs) ? worst.ageMs : null,
+  };
+}
+
+// Minutes, because that is the scale a correction interval lives on and the
+// only one anybody compares against the pulse interval.
+function gap(ms) {
+  if (!Number.isFinite(ms)) return null;
+  const minutes = ms / 60000;
+  return (minutes >= 10 ? Math.round(minutes) : Math.round(minutes * 10) / 10) + 'm';
+}
+
+function describe(codexHome) {
+  const stats = summary(codexHome);
+  if (!stats.sample) return 'Drift ledger: no corrections measured against an earlier one yet.';
+  const lines = [];
+  lines.push('Drift ledger: ' + stats.sample + ' measured correction' + (stats.sample === 1 ? '' : 's') + '.');
+  const medianGap = gap(stats.medianGapMs);
+  const worstGap = gap(stats.worstGapMs);
+  lines.push(
+    '  Percent used: median ' + fmt(stats.medianAbsPercent) + ' points off' +
+      (medianGap ? ' over a typical ' + medianGap + ' gap' : '') + ', worst ' +
+      fmt(stats.worstAbsPercent) + ' points off' + (worstGap ? ' over ' + worstGap : '') + '.'
+  );
+  if (stats.medianAbsTurns !== null) {
+    lines.push(
+      '  Turns left: median ' + fmt(stats.medianAbsTurns) + ' off, worst ' + fmt(stats.worstAbsTurns) + ' off.'
+    );
+  }
+  return lines.join('\n');
+}
+
+function fmt(value) {
+  if (!Number.isFinite(value)) return '-';
+  return Math.round(value * 10) / 10;
+}
+
+function activeCodexHome(argv, env) {
+  return host.detect(argv, env) === host.CODEX ? codex.homeDir() : null;
+}
+
+function main(argv) {
+  const args = argv || [];
+  const codexHome = activeCodexHome(args, process.env);
+  if (args[0] === '--json') return JSON.stringify(summary(codexHome, {}), null, 2);
+  return describe(codexHome);
+}
+
+if (require.main === module) {
+  process.stdout.write(main(process.argv.slice(2)) + '\n');
+  process.exit(0);
+}
+
+module.exports = {
+  MAX_ENTRIES,
+  MAX_MODE_ENTRIES,
+  configDir,
+  driftFile,
+  gap,
+  read,
+  record,
+  recordTurns,
+  modeSummary,
+  summary,
+  describe,
+  main,
+};

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

@@ -204,8 +204,18 @@ function line(built, options) {
         : bars.paint(effortName, effort.rgb, mode);
   // The word, in the rainbow, the way Claude Code paints it in the prompt.
   const thinking = built.ultrathink ? ' ' + bars.dim('·', mode) + ' ' + bars.rainbow('ultrathink', tick, { mode, reduced }) : '';
+  // The budget mode, only when it is not the one the plugin has always been
+  // in. `standard` is today's behaviour and today's line, unchanged to the
+  // character; anything else changes what the hooks say, and a line that does
+  // not mention it leaves the user guessing why the briefing went quiet.
+  // It rides on the head so the width ladder drops it with the head, before it
+  // ever costs a percentage its place.
+  const budgetText =
+    built.budget && built.budget.name !== 'standard'
+      ? ' ' + bars.dim('·', mode) + ' ' + bars.dim('budget ' + built.budget.label, mode)
+      : '';
   const head =
-    glyph + ' ' + built.modelLabel + (effortText ? ' ' + bars.dim('·', mode) + ' ' + effortText : '') + thinking;
+    glyph + ' ' + built.modelLabel + (effortText ? ' ' + bars.dim('·', mode) + ' ' + effortText : '') + thinking + budgetText;
 
   const segment = (row, width, shorter) => {
     const label = shortLabel(row, shorter);
@@ -396,6 +406,17 @@ function motionOff(settings, env) {
 
 // Written and flushed before the process is allowed to end: stdout is a pipe
 // here, and a pipe write can still be in flight when process.exit runs.
+// The budget mode, for the token on the line. Wrapped and lazy: the status
+// line must never fail over an optional word, and a machine that has never set
+// a mode should not pay for a require to be told so.
+function budgetNow(sessionId) {
+  try {
+    return require('./mode.js').forSession({ sessionId });
+  } catch (err) {
+    return null;
+  }
+}
+
 function out(text) {
   return new Promise((resolve) => {
     process.stdout.write(text, () => resolve());
@@ -461,6 +482,7 @@ async function main(argv) {
     const built = view.build({
       now,
       agents: usage.liveAgents(now),
+      budget: budgetNow(mine || (slot && slot.sessionId) || null),
       utilization: collected.utilization,
       fetchedAtMs: collected.snapshotFetchedAt,
       source: collected.snapshotSource,

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

@@ -18,6 +18,15 @@ const path = require('path');
 
 const CLAUDE = 'claude';
 const CODEX = 'codex';
+const GEMINI = 'gemini';
+
+function geminiConfigDir() {
+  return process.env.GEMINI_CONFIG_DIR || path.join(os.homedir(), '.gemini');
+}
+
+function geminiHome() {
+  return process.env.GEMINI_HOME || path.join(geminiConfigDir(), 'antigravity-cli');
+}
 
 function codexHome() {
   return process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
@@ -66,16 +75,20 @@ function codexHasSessions() {
   return exists(path.join(codexHome(), 'sessions'));
 }
 
+function geminiHasSessions() {
+  return exists(geminiHome());
+}
+
 function normalise(value) {
   const name = String(value || '').trim().toLowerCase();
+  if (name === GEMINI || name === 'agy' || name === 'antigravity' || name === 'google') return GEMINI;
   if (name === CODEX || name === 'chatgpt' || name === 'openai') return CODEX;
   if (name === CLAUDE || name === 'claude-code' || name === 'anthropic') return CLAUDE;
   return null;
 }
 
-// `--host codex` beats everything, then the environment variable, then what is
-// actually on disk. Claude wins ties: it is the host the hook was written for,
-// and its reader fails loudly rather than silently reporting nothing.
+// `--host gemini` beats everything, then the environment variable, then what is
+// actually on disk.
 function detect(argv, env) {
   const args = argv || [];
   const at = args.indexOf('--host');
@@ -86,6 +99,8 @@ function detect(argv, env) {
   const fromEnv = normalise(environment.USAGE_LIMITS_HOST);
   if (fromEnv) return fromEnv;
 
+  // Set by Antigravity / Gemini CLI
+  if (environment.ANTIGRAVITY_CLI || environment.GEMINI_CLI || environment.GEMINI_WORKSPACE) return GEMINI;
   // Set by Claude Code for plugin hooks and commands.
   if (environment.CLAUDE_PLUGIN_ROOT || environment.CLAUDE_PROJECT_DIR) return CLAUDE;
   // Set by Codex for the processes it launches.
@@ -93,14 +108,19 @@ function detect(argv, env) {
 
   if (claudeHasSnapshot()) return CLAUDE;
   if (codexHasSessions()) return CODEX;
+  if (geminiHasSessions()) return GEMINI;
   return CLAUDE;
 }
 
 module.exports = {
   CLAUDE,
   CODEX,
+  GEMINI,
   detect,
   normalise,
+  geminiHome,
+  geminiConfigDir,
+  geminiHasSessions,
   codexHome,
   claudeConfigDir,
   claudeHasSnapshot,