claude-token-saver 2.1.0 → 2.5.0

package/src/formatters/statusline.js

@@ -17,12 +17,34 @@
  *   }
  */
 
+import { formatResetClock } from '../format-time.js';
+import { labelForKey } from '../window-labels.js';
+
+// The 8-color ANSI defaults (RED=31, GREEN=32, YELLOW=33…) read as garish
+// next to each other — terminal palettes set them with unbalanced perceptual
+// brightness, so the line ends up feeling loud. We emit a Tailwind-inspired
+// muted palette via 24-bit truecolor when the terminal advertises support
+// (`COLORTERM=truecolor`/`24bit`), and gracefully fall back to the legacy
+// 8-color codes on terminals that don't.
+//
+//   GREEN   → emerald-400 #34D399  (calm, balanced with the others)
+//   YELLOW  → amber-400   #FBBF24  (warm, not screamy)
+//   RED     → rose-400    #FB7185  (alarm without the eye-burn of pure red)
+//   CYAN    → cyan-400    #22D3EE
+//   MAGENTA → violet-400  #A78BFA  (model identity tone)
+//   GRAY    → slate-500   #64748B  (recedes for the gauge track / period footer)
+const TRUECOLOR =
+  process.env.COLORTERM === 'truecolor' || process.env.COLORTERM === '24bit';
+const fg = (r, g, b, fallback) =>
+  TRUECOLOR ? `\x1b[38;2;${r};${g};${b}m` : fallback;
+
 const RESET = '\x1b[0m';
-const RED = '\x1b[31m';
-const GREEN = '\x1b[32m';
-const YELLOW = '\x1b[33m';
-const CYAN = '\x1b[36m';
-const GRAY = '\x1b[90m';
+const RED = fg(251, 113, 133, '\x1b[31m');
+const GREEN = fg(52, 211, 153, '\x1b[32m');
+const YELLOW = fg(251, 191, 36, '\x1b[33m');
+const CYAN = fg(34, 211, 238, '\x1b[36m');
+const MAGENTA = fg(167, 139, 250, '\x1b[35m');
+const GRAY = fg(100, 116, 139, '\x1b[90m');
 const BOLD = '\x1b[1m';
 
 function formatMoney(usd) {
@@ -36,6 +58,44 @@ function formatPct(v) {
   return `${(v * 100).toFixed(1)}%`;
 }
 
+/**
+ * Render a 6-cell density-gradient gauge for `pct` (0..100). All cells share
+ * the same Unicode "Block Elements" density family — `█` (100%) → `▓` (75%)
+ * → `▒` (50%) → `░` (25%) — so the fill→empty boundary reads as one smooth
+ * gradient instead of an awkward step.
+ *
+ * Earlier we used partial-fill glyphs (`▏▎▍▌▋▊▉`) for sub-cell precision, but
+ * those have transparent halves that clash visually with the `░` track next
+ * to them (the eye sees "solid edge | gap | dotted track" — three zones).
+ * Density chars are the same shape, just darker/lighter, so the boundary
+ * cell reads as a single smooth fade.
+ *
+ * Each cell is ~17% wide; the boundary cell uses 3 intermediate density steps
+ * for ~4% effective precision around the fill edge. Stable monospace width
+ * across all terminal fonts that ship Block Elements (U+2580–U+259F).
+ */
+function gaugeBar(pct) {
+  const cells = 6;
+  const clamped = Math.max(0, Math.min(100, pct));
+  const filled = (clamped / 100) * cells; // e.g. 4.32 cells filled
+  const fullCells = Math.floor(filled);
+  const remainder = filled - fullCells; // 0..1 — fill fraction of the boundary cell
+  // Boundary cell: ░ (empty), ▒ (1/3), ▓ (2/3), or roll over to a full █.
+  let partial = '';
+  let extra = 0;
+  if (remainder >= 0.83) {
+    extra = 1; // round up — fill the boundary cell completely
+  } else if (remainder >= 0.5) {
+    partial = '▓';
+  } else if (remainder >= 0.16) {
+    partial = '▒';
+  } // else: remainder is too small to show — leave the cell empty
+  const totalFull = Math.min(cells, fullCells + extra);
+  const usedCells = totalFull + (partial ? 1 : 0);
+  const empty = '░'.repeat(Math.max(0, cells - usedCells));
+  return '█'.repeat(totalFull) + partial + empty;
+}
+
 /**
  * Format a remaining-seconds countdown as MM:SS (or H:MM when ≥ 1h).
  */
@@ -49,6 +109,25 @@ function formatTimer(remainingSec) {
   return `${m}:${String(s).padStart(2, '0')}`;
 }
 
+/**
+ * Pick the cap-warn chip that should surface from any of the rate-limit
+ * windows, or null when none are at 90%+. When multiple windows are warning,
+ * the one that resets sooner wins (it's the more imminent block).
+ */
+export function pickCapWarn(caps) {
+  if (!caps || !Array.isArray(caps.windows)) return null;
+  const candidates = caps.windows
+    .filter((w) => Number.isFinite(w.usedPct) && w.usedPct >= 90)
+    .map((w) => ({ ...w, label: labelForKey(w.key).short }));
+  if (candidates.length === 0) return null;
+  candidates.sort((a, b) => {
+    const ar = Number.isFinite(a.resetsAt) ? a.resetsAt : Infinity;
+    const br = Number.isFinite(b.resetsAt) ? b.resetsAt : Infinity;
+    return ar - br;
+  });
+  return candidates[0];
+}
+
 /**
  * @param {object} data - output of main report pipeline (summary, ttl, cost, options, lastActivity)
  * @param {object} [opts]
@@ -56,9 +135,10 @@ function formatTimer(remainingSec) {
  * @param {boolean} [opts.verbose=false] - longer layout with labels
  * @param {boolean} [opts.timer=true] - show TTL countdown segment
  * @param {'text'|'icon'} [opts.mode='text'] - label style. 'icon' uses 🧠 ⏳ 💰 instead of word labels.
+ * @param {string[]|null} [opts.segments] - whitelist of segments to render. Names: cap-warn, spike, model, hit, ttl, saved, ctx, period, plus per-window keys (`five_hour`, `seven_day`, …). `5h`/`7d` are kept as aliases for back-compat. Null/undefined = all.
  */
-export function formatReport(data, { color = true, verbose = false, timer = true, mode = 'text' } = {}) {
-  const { summary, ttl, cost, options, lastActivity, contextWindow, spikeChip } = data;
+export function formatReport(data, { color = true, verbose = false, timer = true, mode = 'text', segments = null } = {}) {
+  const { summary, ttl, cost, options, lastActivity, contextWindow, spikeChip, caps, model } = data;
   const { hitRate } = summary;
 
   // Hit rate → color signal
@@ -156,12 +236,13 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   if (contextWindow && contextWindow.size && contextWindow.size !== 'unknown') {
     const label = contextWindow.size === '1M' ? '1M' : '200k';
     const ctxColor = contextWindow.size === '1M' ? RED : GREEN;
+    // `Ctx` (not the full word `Context`) across every mode — the icon already
+    // tells the eye what the chip is, and the short form fits the same cadence
+    // as `Hit`/`Saved` peers when we eventually shorten those too.
     if (isIcon && verbose) {
-      ctxSeg = `${c(ctxColor)}📦 Context ${label}${c(RESET)}`;
+      ctxSeg = `${c(ctxColor)}📦 Ctx ${label}${c(RESET)}`;
     } else if (isIcon) {
       ctxSeg = `${c(ctxColor)}📦 ${label}${c(RESET)}`;
-    } else if (verbose) {
-      ctxSeg = `${c(ctxColor)}Context ${label}${c(RESET)}`;
     } else {
       ctxSeg = `${c(ctxColor)}Ctx ${label}${c(RESET)}`;
     }
@@ -170,12 +251,131 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   // Spike chip — one word only, keeps the statusline single-line.
   const spikeSeg = spikeChip ? `${c(RED)}${spikeChip}${c(RESET)}` : null;
 
+  // Model chip — pulled from Claude Code's stdin payload (`model.display_name`).
+  // Cheap identity context: useful when the user toggles between Sonnet/Opus
+  // mid-session and wants to confirm at a glance which one is answering.
+  let modelSeg = null;
+  if (typeof model === 'string' && model.length > 0) {
+    // 🤖 + name is enough — the emoji disambiguates so the literal word "Model"
+    // is dead weight in icon mode. Text modes keep the bare name; the magenta
+    // tone marks it as identity context.
+    if (isIcon) {
+      modelSeg = `${c(MAGENTA)}🤖 ${model}${c(RESET)}`;
+    } else {
+      modelSeg = `${c(MAGENTA)}${model}${c(RESET)}`;
+    }
+  }
+
+  // Always-on usage segments — what /usage shows in Claude Code, mirrored
+  // to the statusline so the user doesn't have to slash-command for it.
+  // Today the stdin payload exposes the 5h ("Current session") and 7-day
+  // rolling ("Current week") windows; if Anthropic ships more (e.g. a
+  // Sonnet-only weekly), they render automatically with derived labels.
+  // Each renders as `{label} {pct}% · {countdown}`. When a window is at >=90%
+  // the cap-warn chip already shouts about it, so we suppress the always-on
+  // segment to avoid duplicate noise.
+  function buildUsageSeg({ labels, info, color: tone }) {
+    if (!info || !Number.isFinite(info.usedPct)) return null;
+    if (info.usedPct >= 90) return null; // cap-warn chip handles this case
+    const pct = Math.round(info.usedPct);
+    // Show only the wall-clock reset time (e.g. `🔄 21:10`). Absolute time
+    // doesn't tick second-by-second so the statusline reads stable, and the
+    // 🔄 icon itself separates the percent from the clock — no extra `·` needed.
+    const clock = formatResetClock(info.resetsAt);
+    const tail = clock ? ` 🔄 ${clock}` : '';
+    // `cap` reads as a rate-limit ceiling rather than a duration. Icon mode
+    // leans on the icon to identify the window (✦ = session/now, 📅 = week),
+    // so the 5H label is empty while the 7D label spells out "weekly". Text and
+    // verbose modes keep the `5H`/`7D` short label since they have no icon.
+    // Icon mode renders an inline ▰▱ gauge instead of the literal "cap used" —
+    // a glance at the bar conveys urgency faster than parsing a percent number,
+    // and the gauge stays the same width as the percent climbs.
+    if (isIcon) {
+      const labelPart = labels.usageLabel ? `${labels.usageLabel} ` : '';
+      const bar = gaugeBar(pct);
+      return `${c(tone)}${labels.icon} ${labelPart}${bar} ${pct}%${tail}${c(RESET)}`;
+    }
+    if (verbose) {
+      return `${c(tone)}${labels.short} cap ${pct}% used${tail}${c(RESET)}`;
+    }
+    return `${c(tone)}${labels.short} cap ${pct}%${tail}${c(RESET)}`;
+  }
+  // Color tone: green when <70%, yellow 70-89% (the segment is suppressed at
+  // 90+% in favor of cap-warn). Lets the user spot "I'm getting close" without
+  // waiting for the alarm chip.
+  function usageTone(info) {
+    if (!info || !Number.isFinite(info.usedPct)) return GRAY;
+    if (info.usedPct >= 70) return YELLOW;
+    return GREEN;
+  }
+  const usageSegs = [];
+  if (caps && Array.isArray(caps.windows)) {
+    for (const win of caps.windows) {
+      const labels = labelForKey(win.key);
+      const seg = buildUsageSeg({
+        labels,
+        info: win,
+        color: usageTone(win),
+      });
+      if (seg) usageSegs.push({ key: win.key, seg });
+    }
+  }
+
+  // Cap-warn chip — leads everything when ANY rate-limit window is at 90%+.
+  // It's the most actionable signal we can show: no point optimizing cache
+  // hits if you're about to be rate-limited anyway. The chip body matches the
+  // English shape `🚨 5H 94%` / `🚨 7D 92%` so history parsers can dedupe on it.
+  const capWarn = pickCapWarn(caps);
+  let capWarnSeg = null;
+  if (capWarn) {
+    const pct = Math.round(capWarn.usedPct);
+    // At 90%+ the user wants to know "when can I send again" — wall-clock is
+    // the actionable bit. Same `🔄 HH:MM` shape as the always-on segments so
+    // the icon's meaning carries over to the alarm chip.
+    const clock = formatResetClock(capWarn.resetsAt);
+    const clockTail = clock ? ` 🔄 ${clock}` : '';
+    if (isIcon) {
+      // Gauge keeps shape parity with the always-on usage segment — the
+      // cap-warn is just the same gauge "filled to alarm". Visual continuity
+      // helps the eye understand "this is the 5H bar I was watching, just red now."
+      const bar = gaugeBar(pct);
+      capWarnSeg = `${c(BOLD)}${c(RED)}🚨 ${capWarn.label} ${bar} ${pct}%${clockTail}${c(RESET)}`;
+    } else {
+      capWarnSeg = `${c(BOLD)}${c(RED)}${capWarn.label} cap ${pct}%${clockTail}${c(RESET)}`;
+    }
+  }
+
   // Warning chip leads — a glance at the statusline catches "something's wrong"
   // before parsing any numbers. Healthy states have no chip and look unchanged.
+  // Cap-warn outranks spike: an imminent rate-limit block is more urgent than
+  // a single spiking session.
+  const allow = segments && segments.length
+    ? new Set(segments.map((s) => s.toLowerCase()))
+    : null;
+  const want = (name) => !allow || allow.has(name);
+  // Legacy whitelist aliases: `5h` ↔ `five_hour`, `7d` ↔ `seven_day`. So
+  // existing `--segments` configs keep working after the generic refactor.
+  const usageWant = (key) => {
+    if (!allow) return true;
+    if (allow.has(key.toLowerCase())) return true;
+    if (key === 'five_hour' && allow.has('5h')) return true;
+    if (key === 'seven_day' && allow.has('7d')) return true;
+    return false;
+  };
   const segs = [];
-  if (spikeSeg) segs.push(spikeSeg);
-  segs.push(hitSeg, ttlSeg, saveSeg);
-  if (ctxSeg) segs.push(ctxSeg);
-  segs.push(periodSeg);
+  if (capWarnSeg && want('cap-warn')) segs.push(capWarnSeg);
+  if (spikeSeg && want('spike')) segs.push(spikeSeg);
+  if (modelSeg && want('model')) segs.push(modelSeg);
+  if (want('hit')) segs.push(hitSeg);
+  if (want('ttl')) segs.push(ttlSeg);
+  for (const { key, seg } of usageSegs) {
+    if (usageWant(key)) segs.push(seg);
+  }
+  if (ctxSeg && want('ctx')) segs.push(ctxSeg);
+  // Cache saved is the "lifetime brag" stat — useful but not actionable, so
+  // it sits near the tail. The period label closes the line as a quiet
+  // timeframe footer.
+  if (want('saved')) segs.push(saveSeg);
+  if (want('period')) segs.push(periodSeg);
   return segs.join(' · ');
 }

package/src/formatters/table.js

@@ -2,6 +2,8 @@
  * Terminal table formatter — zero dependencies.
  */
 import { ISSUE_MESSAGES } from '../advice.js';
+import { formatResetIn, formatResetClock } from '../format-time.js';
+import { labelForKey } from '../window-labels.js';
 
 function pad(str, len, align = 'left') {
   const s = String(str);
@@ -123,7 +125,34 @@ function renderSpikeSection(spikes, contextWindow) {
   return lines;
 }
 
-export function formatReport({ summary: sum, trend, ttl, anomalies, cost, options, spikeReport, contextWindow }) {
+function renderCapWarnSection(caps) {
+  if (!caps || !Array.isArray(caps.windows)) return [];
+  const warning = caps.windows.filter(
+    (w) => Number.isFinite(w.usedPct) && w.usedPct >= 90,
+  );
+  if (warning.length === 0) return [];
+  const lines = [];
+  lines.push('  🚨 Rate-limit cap is closing in');
+  lines.push(`  ${'─'.repeat(50)}`);
+  for (const win of warning) {
+    const label = labelForKey(win.key).long;
+    const reset = formatResetIn(win.resetsAt);
+    const clock = formatResetClock(win.resetsAt);
+    let tail = '';
+    if (reset && clock) tail = `, resets in ${reset} (at ${clock})`;
+    else if (reset) tail = `, resets in ${reset}`;
+    else if (clock) tail = `, resets at ${clock}`;
+    lines.push(`  • ${label}: ${Math.round(win.usedPct)}% used${tail}`);
+  }
+  lines.push('');
+  lines.push('  Back up work before the cap hits:');
+  lines.push('    claude-token-saver handoff');
+  lines.push('  (writes a HANDOFF-*.md so a fresh session can pick up.)');
+  lines.push('');
+  return lines;
+}
+
+export function formatReport({ summary: sum, trend, ttl, anomalies, cost, options, spikeReport, contextWindow, caps }) {
   const lines = [];
 
   // Header
@@ -133,7 +162,12 @@ export function formatReport({ summary: sum, trend, ttl, anomalies, cost, option
   lines.push(`  ${'═'.repeat(50)}`);
   lines.push('');
 
-  // Spike section goes FIRST — it's what the user acts on.
+  // Cap warning leads — it's the most time-sensitive signal we can show.
+  if (caps) {
+    lines.push(...renderCapWarnSection(caps));
+  }
+
+  // Spike section goes next — it's what the user acts on.
   if (spikeReport && spikeReport.spikes.length > 0) {
     lines.push(...renderSpikeSection(spikeReport.spikes, contextWindow));
   }

package/src/handoff.js

@@ -0,0 +1,161 @@
+/**
+ * Handoff template — captures enough state at session-cap time that a fresh
+ * Claude Code session can pick up the work without a long prelude.
+ *
+ * Output: `./HANDOFF-YYYY-MM-DD-HHMM.md` in the caller's cwd. We never
+ * overwrite — if the path is taken we add a `-N` suffix.
+ *
+ * What goes in:
+ *   - Header: timestamp, cwd, git branch / HEAD / dirty file list
+ *   - Cap snapshot: 5h/7d % and resets-in (when known)
+ *   - Empty fillable sections the user pastes context into
+ *   - A one-line resume prompt for the next session
+ */
+
+import { writeFileSync, existsSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { join, resolve } from 'node:path';
+
+import { formatResetIn, formatResetClock } from './format-time.js';
+import { labelForKey } from './window-labels.js';
+
+function pad(n) {
+  return String(n).padStart(2, '0');
+}
+
+function ymd(d = new Date()) {
+  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+
+function hhmm(d = new Date()) {
+  return `${pad(d.getHours())}${pad(d.getMinutes())}`;
+}
+
+function safeGit(cmd, cwd) {
+  try {
+    return execSync(`git ${cmd}`, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return '';
+  }
+}
+
+function gitSnapshot(cwd) {
+  // `rev-parse --git-dir` succeeds in any repo, including a freshly-init'd one
+  // with no commits yet (where `rev-parse HEAD` would fail). We use it as the
+  // "is this a repo?" probe.
+  const gitDir = safeGit('rev-parse --git-dir', cwd);
+  if (!gitDir) return null;
+  const branch = safeGit('rev-parse --abbrev-ref HEAD', cwd) || '(no commits)';
+  const head = safeGit('rev-parse --short HEAD', cwd);
+  const status = safeGit('status --short', cwd);
+  return { branch, head, status };
+}
+
+function pickPath(cwd, now) {
+  const stem = `HANDOFF-${ymd(now)}-${hhmm(now)}`;
+  const direct = join(cwd, `${stem}.md`);
+  if (!existsSync(direct)) return direct;
+  for (let i = 2; i < 100; i++) {
+    const candidate = join(cwd, `${stem}-${i}.md`);
+    if (!existsSync(candidate)) return candidate;
+  }
+  return join(cwd, `${stem}-${Date.now()}.md`);
+}
+
+function renderTemplate({ now, cwd, git, caps }) {
+  const lines = [];
+  lines.push(`# Handoff — ${ymd(now)} ${pad(now.getHours())}:${pad(now.getMinutes())}`);
+  lines.push('');
+  lines.push(`Generated by \`claude-token-saver handoff\`.`);
+  lines.push('');
+  lines.push('## Context');
+  lines.push('');
+  lines.push(`- cwd: \`${cwd}\``);
+  if (git) {
+    lines.push(`- git branch: \`${git.branch}\`${git.head ? ` @ \`${git.head}\`` : ''}`);
+    if (git.status) {
+      lines.push('- dirty files:');
+      lines.push('  ```');
+      for (const line of git.status.split('\n')) lines.push(`  ${line}`);
+      lines.push('  ```');
+    } else {
+      lines.push('- working tree: clean');
+    }
+  } else {
+    lines.push('- git: (not a repo)');
+  }
+  lines.push('');
+
+  lines.push('## Cap snapshot');
+  lines.push('');
+  if (caps && Array.isArray(caps.windows) && caps.windows.length > 0) {
+    for (const win of caps.windows) {
+      const label = labelForKey(win.key).long;
+      if (!Number.isFinite(win.usedPct)) {
+        lines.push(`- ${label}: (unknown)`);
+        continue;
+      }
+      const reset = formatResetIn(win.resetsAt, now);
+      const clock = formatResetClock(win.resetsAt, now);
+      let tail = '';
+      if (reset && clock) tail = `, resets in ${reset} (at ${clock})`;
+      else if (reset) tail = `, resets in ${reset}`;
+      else if (clock) tail = `, resets at ${clock}`;
+      lines.push(`- ${label}: ${Math.round(win.usedPct)}%${tail}`);
+    }
+  } else {
+    lines.push('- (no cap data — run `handoff` from a Claude Code session for live numbers)');
+  }
+  lines.push('');
+
+  lines.push('## What I just did');
+  lines.push('');
+  lines.push('- _(fill in: 1–3 bullets describing the most recent work)_');
+  lines.push('');
+
+  lines.push('## What\'s left (TODO)');
+  lines.push('');
+  lines.push('- [ ] _(fill in)_');
+  lines.push('');
+
+  lines.push('## Where to pick up next');
+  lines.push('');
+  lines.push('- _(file paths, function names, the exact next step)_');
+  lines.push('');
+
+  lines.push('## Watch out for');
+  lines.push('');
+  lines.push('- _(non-obvious gotchas, half-finished refactors, failing tests)_');
+  lines.push('');
+
+  lines.push('## Resume prompt for the next Claude Code session');
+  lines.push('');
+  lines.push('```');
+  lines.push('Read the most recent HANDOFF-*.md in this directory and continue the work.');
+  lines.push('```');
+  lines.push('');
+
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Write a handoff file in the given cwd.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.cwd=process.cwd()]
+ * @param {object|null} [opts.caps] - { windows: [...] } from extractCaps
+ * @param {Date} [opts.now=new Date()]
+ * @returns {{ path: string, git: { branch: string, head: string, status: string } | null }}
+ */
+export function writeHandoff({ cwd = process.cwd(), caps = null, now = new Date() } = {}) {
+  const absCwd = resolve(cwd);
+  const git = gitSnapshot(absCwd);
+  const path = pickPath(absCwd, now);
+  const body = renderTemplate({ now, cwd: absCwd, git, caps });
+  writeFileSync(path, body);
+  return { path, git };
+}