claude-token-saver 2.0.3 → 2.2.0

package/README.md

@@ -9,6 +9,13 @@
 
 **Save tokens on Claude Code.** Catch the session that suddenly burned 10× your usual input, figure out *why*, and get a one-line remediation you can paste.
 
+**Why I built this.** I'm on the Max plan. On Opus 4.6 I never hit the *current-session* cap. After Opus 4.7 rolled out, I started hitting it on the same workflow — repeatedly. The official token statistics didn't match what I was actually feeling, and Claude Code's UI doesn't show prompt-cache health. This tool is what let me see *why*: low cache hit rate, 5m TTL writes that should have been 1h, 1M context auto-promoted in the background.
+
+v2.1 (2026-04) adds the workflow that follows the diagnosis:
+- **`claude-token-saver install`** — one command writes a Claude Code Skill (auto-activates when you mention "cache hit rate" / "1M context" / etc.) and a `/token-monitor` slash command.
+- **`claude-token-saver history`** — every warning chip transition is auto-logged to a daily Markdown file, so you can answer "when did this start" without grepping logs.
+- **Cross-platform paths** — Windows (`%APPDATA%`), macOS (`~/Library/Application Support`), Linux (`~/.config` / XDG) all handled.
+
 v1.5 adds three things on top of the original `claude-cache-monitor`:
 - **Spike diagnosis** — detect recent sessions whose input tokens exploded vs. your own baseline, and name the cause (1M context, 5m TTL churn, cache rebuild, chatty output).
 - **1M-context detection** — Opus 4.7+ auto-enables 1M context on Max plans, silently. This tool surfaces it on the statusline as `Ctx 1M` (red) vs. `Ctx 200k` (green), with the OS-specific command to turn it off.
@@ -16,7 +23,7 @@ v1.5 adds three things on top of the original `claude-cache-monitor`:
 
 The original functionality still works: cache hit rate, TTL breakdown, cost impact vs. no-cache, TTL countdown timer, and Claude Code statusline integration.
 
-**Runs standalone or as a plugin under another statusline.** Use `npx claude-token-saver` as a one-shot report, wire it into Claude Code's native statusline as the sole segment, or drop it in as an appended segment under a richer statusline like [rz1989s/claude-code-statusline](https://github.com/rz1989s/claude-code-statusline). See [Three Ways to Use It](#three-ways-to-use-it).
+**Run it standalone or wire it into Claude Code's statusline.** Use `npx claude-token-saver` as a one-shot report, or wire it into Claude Code's native statusline for an always-on chip. See [Two Ways to Use It](#two-ways-to-use-it).
 
 ---
 
@@ -29,7 +36,7 @@ v1.5 신규:
 
 기존 기능(캐시 히트율·TTL 분포·비용 절감·TTL 카운트다운·statusline)은 그대로 유지됩니다.
 
-**단독 도구로도, 다른 statusline의 플러그인으로도 동작합니다.** `npx claude-token-saver` 한 줄로 진단 리포트만 보는 것도 가능하고, Claude Code 내장 statusline에 직접 연결해 상시 표시할 수도 있고, [rz1989s/claude-code-statusline](https://github.com/rz1989s/claude-code-statusline) 같은 기존 statusline 아래에 세그먼트로 덧붙일 수도 있습니다. 자세한 용법은 [Three Ways to Use It](#three-ways-to-use-it) 참고.
+**단독 도구로도, Claude Code statusline 통합으로도 동작합니다.** `npx claude-token-saver` 한 줄로 진단 리포트만 보거나, 내장 statusline에 연결해 상시 표시할 수 있습니다. 자세한 용법은 [Two Ways to Use It](#two-ways-to-use-it) 참고.
 
 ## Quick Start
 
@@ -92,15 +99,12 @@ Issue codes detected:
 
 Remediation commands are chosen from `process.platform` — macOS/Linux/WSL get `~/.zshrc` snippets, Windows gets `setx` and the PowerShell equivalent.
 
-## Three Ways to Use It
-
-`claude-token-saver` is primarily a **standalone tool**; the plugin mode is just a convenience for users who already run another statusline.
+## Two Ways to Use It
 
 | Mode | What you run | When to pick this |
 |---|---|---|
 | **1. Standalone CLI report** | `npx claude-token-saver` | One-off diagnosis. Prints the full report (spikes + cache + cost + trend). Zero setup. |
-| **2. Standalone Claude Code statusline** | `claude-token-saver --statusline` wired via `~/.claude/settings.json` | You want the chip (hit rate · TTL countdown · Ctx 200k/1M · spike) visible all the time. The default story. |
-| **3. Plugin under another statusline** | `examples/statusline-with-rz1989s.sh` appends our segment to rz1989s or any wrapper script | You already have a rich statusline (repo info, cost, MCP, prayer times, themes) and want to bolt the token-saver segment on the end. |
+| **2. Claude Code statusline** | `claude-token-saver --statusline` wired via `~/.claude/settings.json` | You want the chip (hit rate · TTL countdown · Ctx 200k/1M · spike) visible all the time. |
 
 Detail for each mode below.
 
@@ -186,22 +190,6 @@ Works best in **Windows Terminal** or **PowerShell 7+** (ANSI color + emoji). Cl
 
 Same as Linux — install the package in your WSL Node.js and point to the POSIX sh script.
 
-#### Combine with rz1989s/claude-code-statusline
-
-If you already use [rz1989s/claude-code-statusline](https://github.com/rz1989s/claude-code-statusline) for its rich layout (repo, cost, MCP, prayer times, themes), drop in [`examples/statusline-with-rz1989s.sh`](examples/statusline-with-rz1989s.sh) to append our cache segment at the end — no conflict, no feature overlap.
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "bash ~/.claude/statusline-with-rz1989s.sh",
-    "refreshInterval": 1
-  }
-}
-```
-
----
-
 Claude Code calls this every ~300ms on events, plus once per `refreshInterval` second while idle. Colors are emitted when the terminal supports them:
 
 - **Hit rate** — 🟢 ≥85% · 🟡 70–85% · 🔴 <70%
@@ -212,6 +200,76 @@ Claude Code calls this every ~300ms on events, plus once per `refreshInterval` s
 
 Statusline mode uses the last 7 days by default (override with `--days N`) and never emits multi-line errors, so your statusline stays clean even when there's no session data yet.
 
+## Claude Code integration (`install`) — new in v2.1
+
+One command wires up everything else this README mentions:
+
+```bash
+claude-token-saver install
+```
+
+This writes two files under your Claude user dir:
+- `~/.claude/skills/claude-token-saver/SKILL.md` — auto-activates whenever you mention chip wording ("⚠ 1M ON", "cache miss", etc.) or ask about token usage. Claude Code will then know to read history, drill into the table report, and explain the warning.
+- `~/.claude/commands/token-monitor.md` — adds a `/token-monitor` slash command that runs `claude-token-saver history` + a fresh report and summarizes both for you.
+
+Re-run with `--force` to overwrite. Install only one piece with `install --skill` or `install --command`.
+
+## Warning history (`history`) — new in v2.1
+
+The statusline path auto-logs every chip transition (none → ⚠, ⚠ A → ⚠ B, ⚠ → resolved) to a daily Markdown file. Read it back with:
+
+```bash
+claude-token-saver history             # last 7 days
+claude-token-saver history --days 30   # wider window
+claude-token-saver history --list      # just list available dates
+```
+
+Sample output:
+
+```
+# Token Monitor — 2026-04-25
+
+## Events
+- 09:14:02 ⚠ 1M ON  — Context auto-promoted to 1M (max single-request 280k tokens)
+- 09:42:18 ⚠ 1M ON → ⚠ Cache miss  — session abc12345: LOW_HIT_RATE
+- 10:05:47 ✓ resolved (was ⚠ Cache miss)
+```
+
+Storage paths (cross-platform):
+- **Windows**: `%APPDATA%\claude-token-saver\history\YYYY-MM-DD.md`
+- **macOS**: `~/Library/Application Support/claude-token-saver/history/YYYY-MM-DD.md`
+- **Linux**: `$XDG_CONFIG_HOME/claude-token-saver/history/YYYY-MM-DD.md` (or `~/.config/...`)
+
+Each day's file is plain Markdown — open it in any editor. Transitions are deduped, so the 1Hz statusline refresh doesn't spam.
+
+## Cap-warn + handoff (new in v2.2)
+
+Claude Code's statusline payload now includes rate-limit usage (`rate_limits.five_hour.used_percentage`, `rate_limits.seven_day.used_percentage`). claude-token-saver leads the statusline with a `🚨 5H 94%` (or `🚨 7D 92%`) chip the moment either window crosses **90%**, and writes the transition into history:
+
+```
+- 14:32:08 🚨 5H 94% cap warning (resets in 1h 38m)
+- 16:10:21 ✓ 5H cap warning resolved
+```
+
+When you see the chip, back up the work in flight before the cap blocks you:
+
+```bash
+claude-token-saver handoff
+```
+
+That writes `./HANDOFF-YYYY-MM-DD-HHMM.md` in the current directory with:
+
+- timestamp, cwd, git branch / HEAD / dirty file list
+- the 5h/7d cap snapshot (and "resets in Hh Mm")
+- empty fillable sections for *what I just did*, *TODO*, *where to pick up next*, *gotchas*
+- a one-line resume prompt for a fresh Claude Code session:
+
+  ```
+  Read the most recent HANDOFF-*.md in this directory and continue the work.
+  ```
+
+The handoff write is also recorded in history (`📝 handoff written: …`), so `/token-monitor` and `claude-token-saver history` show both the cap-warn and the backup event next to each other.
+
 ## Hook Setup
 
 Automatically logs cache stats on every tool call and alerts when hit rate drops below a threshold.

package/bin/cli.js

@@ -26,6 +26,50 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 
+/**
+ * Read the JSON blob Claude Code feeds the statusline command on stdin.
+ * Returns null when stdin is a TTY or empty (e.g. user invokes `--statusline`
+ * by hand) so callers can fall back to flag/env config.
+ *
+ * The blob shape (subset we consume):
+ *   {
+ *     "transcript_path": "...",
+ *     "rate_limits": {
+ *       "five_hour":  { "used_percentage": 94, "resets_at": 1777099200 },
+ *       "seven_day":  { "used_percentage": 7,  "resets_at": 1777521600 }
+ *     }
+ *   }
+ */
+function readStdinJson() {
+  if (process.stdin.isTTY) return null;
+  try {
+    const raw = readFileSync(0, 'utf8');
+    if (!raw || !raw.trim()) return null;
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function extractCaps(stdinJson) {
+  if (!stdinJson || !stdinJson.rate_limits) return null;
+  const rl = stdinJson.rate_limits;
+  const pick = (obj) => {
+    if (!obj || typeof obj !== 'object') return null;
+    const used = Number(obj.used_percentage);
+    if (!Number.isFinite(used)) return null;
+    const resetsAt = Number(obj.resets_at);
+    return {
+      usedPct: used,
+      resetsAt: Number.isFinite(resetsAt) ? resetsAt : null,
+    };
+  };
+  return {
+    fiveHour: pick(rl.five_hour),
+    sevenDay: pick(rl.seven_day),
+  };
+}
+
 import { parseAllSessions, getLastUserMessageTime } from '../src/parser.js';
 import {
   dailyTrend,
@@ -53,8 +97,11 @@ const PKG_VERSION = (() => {
 
 function getArg(name) {
   const idx = args.indexOf(name);
-  if (idx === -1) return undefined;
-  return args[idx + 1];
+  if (idx !== -1) return args[idx + 1];
+  const prefix = `${name}=`;
+  const eq = args.find((a) => a.startsWith(prefix));
+  if (eq) return eq.slice(prefix.length);
+  return undefined;
 }
 
 function hasFlag(name) {
@@ -62,6 +109,141 @@ function hasFlag(name) {
 }
 
 async function main() {
+  // Subcommand: history — print recent warning transitions captured by the
+  // statusline. One markdown file per day, persisted under the platform-
+  // specific user-data dir.
+  //   claude-token-saver history              # last 7 days
+  //   claude-token-saver history --days 30    # custom window
+  //   claude-token-saver history --list       # just list available dates
+  if (args[0] === 'history') {
+    const { readRecent, listDates, historyDir } = await import('../src/history.js');
+    if (hasFlag('--list')) {
+      const dates = listDates();
+      if (dates.length === 0) {
+        console.log(`No history yet. Files will appear under: ${historyDir()}`);
+        return;
+      }
+      console.log(`History (${historyDir()}):`);
+      for (const d of dates) console.log(`  ${d}`);
+      return;
+    }
+    const days = parseFloat(getArg('--days') || '7');
+    const recent = readRecent(days);
+    if (recent.length === 0) {
+      console.log(`No warning history in the last ${days} day${days === 1 ? '' : 's'}.`);
+      console.log(`(Files would be written to: ${historyDir()})`);
+      return;
+    }
+    for (const { content } of recent) {
+      console.log(content.replace(/\n+$/, ''));
+      console.log('');
+    }
+    return;
+  }
+
+  // Subcommand: handoff — write a HANDOFF-YYYY-MM-DD-HHMM.md template in cwd
+  // capturing git status + the latest cap snapshot, so a fresh Claude Code
+  // session can pick up where this one stopped. Pairs with the cap-warn chip:
+  // when statusline shows 🚨 5H 90%+, run this to back up state before the cap
+  // hits.
+  //   claude-token-saver handoff             # write to cwd
+  //   claude-token-saver handoff --cwd PATH  # custom directory
+  if (args[0] === 'handoff') {
+    const { writeHandoff } = await import('../src/handoff.js');
+    const { recordHandoff } = await import('../src/history.js');
+    const cwd = getArg('--cwd') || process.cwd();
+    // Cap data only flows in via stdin (Claude Code statusline contract).
+    // Direct CLI invocations won't have it — that's fine, the template will
+    // note the gap.
+    const stdinJson = readStdinJson();
+    const caps = extractCaps(stdinJson);
+    const { path, git } = writeHandoff({ cwd, caps });
+    try { recordHandoff(path); } catch { /* non-critical */ }
+    console.log(`Handoff written: ${path}`);
+    if (git) {
+      console.log(`  git: ${git.branch}${git.head ? ` @ ${git.head}` : ''}${git.status ? ' (dirty)' : ' (clean)'}`);
+    }
+    console.log('');
+    console.log('Fill in the empty sections, then start a new Claude Code session with:');
+    console.log('  Read the most recent HANDOFF-*.md in this directory and continue the work.');
+    return;
+  }
+
+  // Subcommand: install — write the Claude Code Skill and slash command so
+  // /token-monitor and the auto-trigger skill become available without any
+  // manual file editing. Cross-platform (uses node:path + node:fs).
+  //   claude-token-saver install              # install both
+  //   claude-token-saver install --skill      # only the skill
+  //   claude-token-saver install --command    # only the slash command
+  //   claude-token-saver install --force      # overwrite existing files
+  if (args[0] === 'install') {
+    const { installSkill, installCommand, installAll } = await import('../src/installer.js');
+    const force = hasFlag('--force');
+    const onlySkill = hasFlag('--skill');
+    const onlyCommand = hasFlag('--command');
+    const print = (kind, r) => {
+      const verb = r.action === 'exists' ? 'already exists' : r.action;
+      console.log(`  ${kind}: ${r.path} (${verb})`);
+    };
+    if (onlySkill && !onlyCommand) {
+      print('skill', installSkill({ force }));
+    } else if (onlyCommand && !onlySkill) {
+      print('command', installCommand({ force }));
+    } else {
+      const r = installAll({ force });
+      print('skill', r.skill);
+      print('command', r.command);
+    }
+    console.log('');
+    console.log('Open Claude Code in any directory and try:');
+    console.log('  /token-monitor');
+    console.log('Or just mention "cache hit rate" / "1M context" — the skill auto-activates.');
+    if (!force) {
+      console.log('');
+      console.log('Tip: re-run with --force to overwrite existing files.');
+    }
+    return;
+  }
+
+  // Subcommand: mode — persist statusline preferences so future runs pick
+  // them up without flags or wrapper edits.
+  //   claude-token-saver mode                    # show current config
+  //   claude-token-saver mode icon verbose       # set icon + verbose
+  //   claude-token-saver mode reset              # clear back to defaults
+  if (args[0] === 'mode') {
+    const { applyMode, loadConfig, configPath, statuslineDefaults, VALID_KEYWORDS } =
+      await import('../src/config.js');
+    const words = args.slice(1);
+    if (words.length === 0) {
+      const eff = statuslineDefaults();
+      const raw = loadConfig().statusline || {};
+      console.log('Statusline mode (effective):');
+      console.log(`  icon:    ${eff.icon}`);
+      console.log(`  verbose: ${eff.verbose}`);
+      console.log(`  timer:   ${eff.timer}`);
+      console.log(`  color:   ${eff.color}`);
+      console.log(`  window:  ${eff.windowLabel} (${eff.windowHours}h)`);
+      console.log('');
+      console.log(`Stored config (${configPath()}):`);
+      console.log(`  ${Object.keys(raw).length === 0 ? '(none — using defaults)' : JSON.stringify(raw)}`);
+      console.log('');
+      console.log('Change with: claude-token-saver mode <keywords...>');
+      console.log(`Keywords: ${VALID_KEYWORDS.join(', ')}`);
+      return;
+    }
+    const { applied, unknown } = applyMode(words);
+    if (unknown.length) {
+      console.error(`Unknown keyword${unknown.length > 1 ? 's' : ''}: ${unknown.join(', ')}`);
+      console.error(`Valid: ${VALID_KEYWORDS.join(', ')}`);
+      process.exit(1);
+    }
+    const eff = statuslineDefaults();
+    console.log(`Updated: ${applied.join(', ')}`);
+    console.log(`Now: icon=${eff.icon} verbose=${eff.verbose} timer=${eff.timer} color=${eff.color} window=${eff.windowLabel}`);
+    console.log('Statusline picks up the change on the next refresh (~1s).');
+    return;
+  }
+
   // Hook management
   if (hasFlag('--install-hook')) {
     const { installHook } = await import('../src/hook-manager.js');
@@ -85,10 +267,94 @@ async function main() {
   // Statusline mode shortcut
   const isStatusline = hasFlag('--statusline') || getArg('--format') === 'statusline';
 
+  // Demo mode — render synthetic warning-case data through the real
+  // formatter for screencasts/marketing GIFs. `--demo cycle` rotates through
+  // every scenario based on wall clock so a screen recorder picks them up.
+  const demoArg = getArg('--demo');
+
+  // `claude-token-saver --demo table` (no --statusline) — full table view
+  // with all six issue drill-downs at once, for marketing screencasts.
+  if (!isStatusline && demoArg === 'table') {
+    const { buildTableDemoData } = await import('../src/demo.js');
+    const { formatReport } = await import('../src/formatters/table.js');
+    const data = buildTableDemoData({ version: PKG_VERSION });
+    console.log(formatReport(data));
+    return;
+  }
+
+  if (isStatusline && demoArg) {
+    const { buildScenarioData, listScenarios } = await import('../src/demo.js');
+    const { statuslineDefaults } = await import('../src/config.js');
+    const cfg = statuslineDefaults();
+    const cycleSeconds = parseFloat(getArg('--demo-cycle-sec') || '3');
+    const data = buildScenarioData(demoArg, {
+      cycleSeconds,
+      windowHours: cfg.windowHours,
+      windowLabel: cfg.windowLabel,
+      days: cfg.windowHours / 24,
+      version: PKG_VERSION,
+    });
+    if (!data) {
+      const known = listScenarios().map((s) => s.name).concat(['cycle']).join(', ');
+      console.error(`Unknown demo scenario: ${demoArg}`);
+      console.error(`Valid: ${known}`);
+      process.exit(1);
+    }
+    const { formatReport } = await import('../src/formatters/statusline.js');
+    const isIcon = hasFlag('--icon')
+      ? true
+      : (hasFlag('--no-icon') || hasFlag('--text') ? false : cfg.icon);
+    const isVerbose = hasFlag('--verbose')
+      ? true
+      : (hasFlag('--no-verbose') || hasFlag('--compact') ? false : cfg.verbose);
+    const showTimer = hasFlag('--no-timer') ? false : cfg.timer;
+    const colorOk = !hasFlag('--no-color') && !process.env.NO_COLOR && cfg.color;
+    const segmentsArg = getArg('--segments');
+    const segments = segmentsArg
+      ? segmentsArg.split(',').map((s) => s.trim()).filter(Boolean)
+      : null;
+    const out = formatReport(data, {
+      color: colorOk,
+      verbose: isVerbose,
+      timer: showTimer,
+      mode: isIcon ? 'icon' : 'text',
+      segments,
+    });
+    // For `cycle` mode, prefix with the scenario label so the screen recorder
+    // shows what the viewer is looking at (only when explicitly requested).
+    if (demoArg === 'cycle' && hasFlag('--demo-label')) {
+      const gray = colorOk ? '\x1b[90m' : '';
+      const reset = colorOk ? '\x1b[0m' : '';
+      console.log(`${gray}[${data._demoLabel}]${reset}  ${out}`);
+    } else {
+      console.log(out);
+    }
+    return;
+  }
+
   // Report generation
-  // Statusline default = 7 days (fast, called every ~300ms). Others = 30 days.
-  const defaultDays = isStatusline ? 7 : 30;
-  const days = parseInt(getArg('--days') || getArg('-d') || String(defaultDays), 10);
+  // Statusline window comes from persisted config — hours-precise so users
+  // can pick `1h` / `6h` etc, not just whole days. Other formats default to
+  // 30 days as before.
+  let windowHours = 30 * 24;
+  let windowLabel = '30d';
+  if (isStatusline) {
+    const { statuslineDefaults } = await import('../src/config.js');
+    const d = statuslineDefaults();
+    windowHours = d.windowHours;
+    windowLabel = d.windowLabel;
+  }
+  // CLI overrides: --hours wins over --days; both win over config.
+  const hoursArg = getArg('--hours');
+  const daysArg = getArg('--days') || getArg('-d');
+  if (hoursArg !== undefined) {
+    windowHours = parseFloat(hoursArg);
+    windowLabel = `${windowHours}h`;
+  } else if (daysArg !== undefined) {
+    windowHours = parseFloat(daysArg) * 24;
+    windowLabel = `${parseFloat(daysArg)}d`;
+  }
+  const days = windowHours / 24;
   const format = isStatusline ? 'statusline' : (getArg('--format') || getArg('-f') || 'table');
   const projectFilter = getArg('--project') || getArg('-p');
 
@@ -132,13 +398,39 @@ async function main() {
   const spikeReport = detectSpikes(sessions, { recentHours: 24, multiplier: 3 });
   const contextWindow = detectContextWindow(sessions, { recentHours: 24 });
 
+  // Claude Code feeds the statusline command a JSON blob on stdin every
+  // refresh. Pull rate_limits out of it so we can surface cap-warn (>=90%)
+  // chips, record cap transitions, and seed the table view's warning box.
+  // The table path falls back to the most-recent cached snapshot so the
+  // /token-monitor slash command (which doesn't pipe stdin) still warns.
+  const stdinJson = readStdinJson();
+  let caps = extractCaps(stdinJson);
+  if (isStatusline && caps) {
+    try {
+      const { persistCaps } = await import('../src/caps-cache.js');
+      persistCaps(caps);
+    } catch {
+      // non-critical
+    }
+  }
+  if (!isStatusline && !caps) {
+    try {
+      const { loadRecentCaps } = await import('../src/caps-cache.js');
+      caps = loadRecentCaps();
+    } catch {
+      // ignore
+    }
+  }
+
   // For statusline: attach a single-word chip only when there's something
   // actionable right now. 1M context is always shown; otherwise only fire
   // if the most recent session actually appears in the spike list.
   let spikeChip = null;
+  let chipDetail = null;
   if (format === 'statusline') {
     if (contextWindow.size === '1M') {
       spikeChip = chipForIssues([], contextWindow);
+      chipDetail = `Context auto-promoted to 1M (max single-request ${Math.round(contextWindow.maxContext / 1000)}k tokens)`;
     } else {
       const recentSession = sessions
         .slice()
@@ -150,8 +442,27 @@ async function main() {
         const m = sessionMetrics(recentSession);
         const issues = diagnoseSession(m, spikeReport.baseline);
         spikeChip = chipForIssues(issues, contextWindow);
+        const titles = issues
+          .map((i) => i.code)
+          .slice(0, 2)
+          .join(', ');
+        chipDetail = `session ${recentSession.sessionId?.slice(0, 8) || ''}: ${titles}`;
       }
     }
+    // Persist transitions to ~/.config/claude-token-saver/history/YYYY-MM-DD.md
+    // so /token-monitor and `claude-token-saver history` can replay them.
+    try {
+      const { recordChip, recordCapTransition } = await import('../src/history.js');
+      recordChip(spikeChip, { detail: chipDetail });
+      // Cap-warn transitions are tracked independently per window — a session
+      // can hit 90% on the 5h window even when no spike chip is firing.
+      if (caps) {
+        recordCapTransition('five_hour', caps.fiveHour);
+        recordCapTransition('seven_day', caps.sevenDay);
+      }
+    } catch {
+      // history is non-critical — don't let it break the statusline render
+    }
   }
 
   // Last API activity feeds the statusline TTL countdown.
@@ -181,11 +492,12 @@ async function main() {
     ttl,
     anomalies,
     cost,
-    options: { days, version: PKG_VERSION },
+    options: { days, windowHours, windowLabel, version: PKG_VERSION },
     lastActivity,
     spikeReport,
     contextWindow,
     spikeChip,
+    caps,
   };
 
   let output;
@@ -197,13 +509,30 @@ async function main() {
     output = formatReport(data);
   } else if (format === 'statusline') {
     const { formatReport } = await import('../src/formatters/statusline.js');
-    const colorOk = !hasFlag('--no-color') && !process.env.NO_COLOR;
-    const mode = hasFlag('--icon') ? 'icon' : 'text';
+    const { statuslineDefaults } = await import('../src/config.js');
+    const cfg = statuslineDefaults();
+
+    // CLI flags take precedence; otherwise fall back to persisted config.
+    const isIcon = hasFlag('--icon')
+      ? true
+      : (hasFlag('--no-icon') || hasFlag('--text') ? false : cfg.icon);
+    const isVerbose = hasFlag('--verbose')
+      ? true
+      : (hasFlag('--no-verbose') || hasFlag('--compact') ? false : cfg.verbose);
+    const showTimer = hasFlag('--no-timer') ? false : cfg.timer;
+    const colorOk =
+      !hasFlag('--no-color') && !process.env.NO_COLOR && cfg.color;
+
+    const segmentsArg = getArg('--segments');
+    const segments = segmentsArg
+      ? segmentsArg.split(',').map((s) => s.trim()).filter(Boolean)
+      : null;
     output = formatReport(data, {
       color: colorOk,
-      verbose: hasFlag('--verbose'),
-      timer: !hasFlag('--no-timer'),
-      mode,
+      verbose: isVerbose,
+      timer: showTimer,
+      mode: isIcon ? 'icon' : 'text',
+      segments,
     });
   } else {
     const { formatReport } = await import('../src/formatters/table.js');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "2.0.3",
+  "version": "2.2.0",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {