claude-token-saver 2.1.0 → 2.5.0

package/README.md

@@ -23,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).
 
 ---
 
@@ -36,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
 
@@ -99,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.
 
@@ -193,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%
@@ -261,6 +242,52 @@ Storage paths (cross-platform):
 
 Each day's file is plain Markdown — open it in any editor. Transitions are deduped, so the 1Hz statusline refresh doesn't spam.
 
+## Model + /usage segments (new in v2.3, generic in v2.4)
+
+Three more segments mirror the data Claude Code's `/usage` slash command shows, so you don't have to slash for it every few minutes:
+
+| Segment     | Icon mode example     | Source                          |
+| ----------- | --------------------- | ------------------------------- |
+| `model`     | `🤖 Opus 4.7`         | stdin `model.display_name`      |
+| `five_hour` | `✦ current ███▒░░ 47% 🔄 21:10`     | stdin `rate_limits.five_hour`   |
+| `seven_day` | `📅 weekly ▒░░░░░ 9% 🔄 Thu 13:00`   | stdin `rate_limits.seven_day`   |
+
+The window segments stay quiet under 70% (calm emerald), warm to amber at 70–89%, and yield to the leading `🚨 5H █████▓ 94%` / `🚨 7D █████▒ 92%` cap-warn chip at 90%+ — so you never see the same window twice. The gauge is 6 cells wide using a single density family (`█▓▒░`), so the fill→empty boundary reads as one smooth gradient instead of an awkward step between fractional and shaded glyphs. Colors render as a Tailwind-inspired muted palette (emerald-400 / amber-400 / rose-400) on truecolor terminals (`COLORTERM=truecolor`), with a graceful fallback to 8-color ANSI elsewhere. Filter the layout with `--segments=` if you only want a subset:
+
+```bash
+claude-token-saver --statusline --icon --segments=model,five_hour,seven_day,saved
+```
+
+`5h` and `7d` are kept as aliases for the older config files. Any new `rate_limits.*` window Anthropic ships (e.g. a Sonnet-only weekly bucket) renders automatically with a derived label — no config or version bump needed. As of 2026-04-25 the stdin contract exposes only `five_hour` + `seven_day`; the third row in `/usage` ("Current week — Sonnet only") is not in the payload yet, so we mirror what's there.
+
+## 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,66 @@ 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 }
+ *     }
+ *   }
+ *
+ * extractCaps treats `rate_limits` as a generic object so any future window
+ * Anthropic adds (e.g. a Sonnet-only weekly bucket) flows through without code
+ * changes — known keys get curated labels, unknowns get derived ones.
+ */
+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 || typeof stdinJson.rate_limits !== 'object') return null;
+  const windows = [];
+  for (const [key, value] of Object.entries(stdinJson.rate_limits)) {
+    if (!value || typeof value !== 'object') continue;
+    const usedPct = Number(value.used_percentage);
+    if (!Number.isFinite(usedPct)) continue;
+    const resetsAt = Number(value.resets_at);
+    windows.push({
+      key,
+      usedPct,
+      resetsAt: Number.isFinite(resetsAt) ? resetsAt : null,
+    });
+  }
+  return windows.length ? { windows } : null;
+}
+
+/**
+ * Pull the human-friendly model name out of Claude Code's stdin payload.
+ * `model.display_name` is the contract; fall back to `model.id` when it's
+ * absent. Returns null when nothing usable is in the JSON.
+ */
+function extractModel(stdinJson) {
+  if (!stdinJson || !stdinJson.model) return null;
+  const m = stdinJson.model;
+  if (typeof m === 'string') return m;
+  if (typeof m.display_name === 'string' && m.display_name) return m.display_name;
+  if (typeof m.id === 'string' && m.id) return m.id;
+  return null;
+}
+
 import { parseAllSessions, getLastUserMessageTime } from '../src/parser.js';
 import {
   dailyTrend,
@@ -53,15 +113,162 @@ 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) {
   return args.includes(name);
 }
 
+/**
+ * Scan recent history file contents (newest day first) and return the most
+ * recent warning event — `{ time, chip, detail, codes, isCap, capLabel, capPct }`.
+ * Returns null when no warning is found in the window.
+ *
+ * Recognized event lines (from history.js appendDayLine output):
+ *   - HH:MM:SS ⚠ Cache miss — session abc1: LOW_HIT_RATE
+ *   - HH:MM:SS ⚠ A → ⚠ B — detail
+ *   - HH:MM:SS 🚨 5H 94% cap warning (resets in ...)
+ *   - HH:MM:SS ✓ resolved (was ...)        ← skip
+ *   - HH:MM:SS ✓ 5H cap warning resolved   ← skip
+ *   - HH:MM:SS 📝 handoff written: ...     ← skip
+ */
+function findLatestWarning(historyEntries, chipToCodes) {
+  const warnings = [];
+  for (const { date, content } of historyEntries) {
+    const lines = content.split('\n');
+    for (const line of lines) {
+      // Skip non-event lines
+      const m = line.match(/^- (\d{2}:\d{2}:\d{2})\s+(.+)$/);
+      if (!m) continue;
+      const time = m[1];
+      const rest = m[2];
+      // Skip resolutions and handoff entries
+      if (rest.startsWith('✓ ') || rest.startsWith('📝 ')) continue;
+      // Cap-warn line: `🚨 5H 94% cap warning (...)`
+      const cap = rest.match(/^🚨\s+(\S+)\s+(\d+)%\s+cap warning(?:\s*\((.+)\))?$/);
+      if (cap) {
+        warnings.push({
+          date,
+          time,
+          chip: `🚨 ${cap[1]} ${cap[2]}%`,
+          isCap: true,
+          capLabel: cap[1],
+          capPct: parseInt(cap[2], 10),
+          capReset: cap[3] || null,
+          codes: [],
+          detail: null,
+        });
+        continue;
+      }
+      // Chip line — last token after the chip is `— detail` (optional). The
+      // chip itself can be a plain `⚠ X` or a `⚠ A → ⚠ B` transition; we want
+      // the *current* chip (right side of the arrow if present).
+      const arrowMatch = rest.match(/^(.+?)\s+→\s+(.+?)(?:\s+—\s+(.+))?$/);
+      let chip;
+      let detail = null;
+      if (arrowMatch) {
+        chip = arrowMatch[2].trim();
+        detail = arrowMatch[3] || null;
+      } else {
+        const plain = rest.match(/^(\S+(?:\s+\S+)*?)(?:\s+—\s+(.+))?$/);
+        if (!plain) continue;
+        chip = plain[1].trim();
+        detail = plain[2] || null;
+      }
+      // Resolve codes: detail "session ID: A, B" → codes; else CHIP_TO_CODES.
+      const codes = [];
+      if (detail) {
+        const dm = detail.match(/^session [^:]+:\s*(.+)$/);
+        if (dm) {
+          for (const c of dm[1].split(',').map((s) => s.trim()).filter(Boolean)) {
+            if (!codes.includes(c)) codes.push(c);
+          }
+        }
+      }
+      if (chipToCodes[chip]) {
+        for (const c of chipToCodes[chip]) if (!codes.includes(c)) codes.push(c);
+      }
+      warnings.push({ date, time, chip, isCap: false, codes, detail });
+    }
+  }
+  return warnings.length ? warnings[warnings.length - 1] : null;
+}
+
 async function main() {
+  // Subcommand: last — print the most recent warning + how to handle it.
+  // Designed for the /token-monitor slash command and the auto-skill so the
+  // user immediately sees "what just fired and how to fix it" without having
+  // to read the whole history file.
+  //   claude-token-saver last           # search last 1 day
+  //   claude-token-saver last --days 7  # widen the lookback
+  if (args[0] === 'last') {
+    const { readRecent, historyDir } = await import('../src/history.js');
+    const { ISSUE_MESSAGES, CHIP_TO_CODES, CAP_TIPS } = await import('../src/advice.js');
+    const days = parseFloat(getArg('--days') || '1');
+    const recent = readRecent(days);
+    const latest = findLatestWarning(recent, CHIP_TO_CODES);
+    if (!latest) {
+      console.log(`No warnings in the last ${days} day${days === 1 ? '' : 's'}.`);
+      console.log(`(History dir: ${historyDir()})`);
+      return;
+    }
+    // Header
+    console.log(`Most recent warning — ${latest.date} ${latest.time}`);
+    console.log(`  ${latest.chip}${latest.detail ? `  — ${latest.detail}` : ''}`);
+    console.log('');
+    // Cap-warn path: handoff is the recommendation. Print the bilingual tip
+    // and a one-line "how to back up" pointer.
+    if (latest.isCap) {
+      if (latest.capReset) console.log(`  Cap window: ${latest.capReset}`);
+      console.log('');
+      console.log('💡 ' + CAP_TIPS.en);
+      console.log('💡 ' + CAP_TIPS.ko);
+      console.log('');
+      console.log('Run:');
+      console.log('  claude-token-saver handoff');
+      return;
+    }
+    // Chip warning path: render full ISSUE_MESSAGES advice for each code,
+    // bilingual (English first, `└ Korean` continuation per line — matches
+    // the history.md format).
+    if (latest.codes.length === 0) {
+      console.log('(No diagnostic code attached — open the table view: `claude-token-saver --days 1`)');
+      console.log('(진단 코드 없음 — 표 뷰를 열어보세요: `claude-token-saver --days 1`)');
+      return;
+    }
+    for (const code of latest.codes) {
+      const msg = ISSUE_MESSAGES[code];
+      if (!msg) {
+        console.log(`Code: ${code} (no advice registered)`);
+        continue;
+      }
+      console.log(`▎ ${msg.title}`);
+      if (msg.titleKo && msg.titleKo !== msg.title) console.log(`  └ ${msg.titleKo}`);
+      console.log(`  ${msg.explain}`);
+      if (msg.explainKo && msg.explainKo !== msg.explain) console.log(`  └ ${msg.explainKo}`);
+      const actions = typeof msg.actions === 'function' ? msg.actions() : msg.actions || [];
+      for (const a of actions) {
+        console.log('');
+        console.log(`  ${a.label}:`);
+        if (a.labelKo && a.labelKo !== a.label) console.log(`  └ ${a.labelKo}:`);
+        const cmds = a.commands || [];
+        const cmdsKo = a.commandsKo || [];
+        for (let i = 0; i < cmds.length; i++) {
+          console.log(`    - ${cmds[i]}`);
+          const ko = cmdsKo[i];
+          if (ko && ko !== cmds[i]) console.log(`      └ ${ko}`);
+        }
+      }
+      console.log('');
+    }
+    return;
+  }
+
   // Subcommand: history — print recent warning transitions captured by the
   // statusline. One markdown file per day, persisted under the platform-
   // specific user-data dir.
@@ -94,6 +301,34 @@ async function main() {
     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).
@@ -234,11 +469,16 @@ async function main() {
       : (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).
@@ -318,6 +558,36 @@ 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 + model out of it so we can surface cap-warn
+  // (>=90%) chips, always-on usage segments, the model chip, 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 has the data.
+  const stdinJson = readStdinJson();
+  let caps = extractCaps(stdinJson);
+  let model = extractModel(stdinJson);
+  if (isStatusline && (caps || model)) {
+    try {
+      const { persistSnapshot } = await import('../src/caps-cache.js');
+      persistSnapshot({ caps, model });
+    } catch {
+      // non-critical
+    }
+  }
+  if (!isStatusline && (!caps || !model)) {
+    try {
+      const { loadRecentSnapshot } = await import('../src/caps-cache.js');
+      const snap = loadRecentSnapshot();
+      if (snap) {
+        if (!caps && snap.caps) caps = snap.caps;
+        if (!model && snap.model) model = snap.model;
+      }
+    } 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.
@@ -348,8 +618,13 @@ async function main() {
     // 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 } = await import('../src/history.js');
+      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 && Array.isArray(caps.windows)) {
+        for (const win of caps.windows) recordCapTransition(win);
+      }
     } catch {
       // history is non-critical — don't let it break the statusline render
     }
@@ -387,6 +662,8 @@ async function main() {
     spikeReport,
     contextWindow,
     spikeChip,
+    caps,
+    model,
   };
 
   let output;
@@ -412,11 +689,16 @@ async function main() {
     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: 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.1.0",
+  "version": "2.5.0",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {