claude-token-saver 2.1.0 → 2.2.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,34 @@ 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.
 
+## 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) {
@@ -94,6 +141,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 +309,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 +398,30 @@ 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.
@@ -348,8 +452,14 @@ 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) {
+        recordCapTransition('five_hour', caps.fiveHour);
+        recordCapTransition('seven_day', caps.sevenDay);
+      }
     } catch {
       // history is non-critical — don't let it break the statusline render
     }
@@ -387,6 +497,7 @@ async function main() {
     spikeReport,
     contextWindow,
     spikeChip,
+    caps,
   };
 
   let output;
@@ -412,11 +523,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.2.0",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {

package/src/caps-cache.js

@@ -0,0 +1,51 @@
+/**
+ * Caps cache — the rate-limit numbers only flow through stdin from Claude
+ * Code's statusline contract, but we want the table view (e.g. invoked by
+ * `/token-monitor`) to surface the same cap-warn box. So whenever the
+ * statusline path sees caps it writes them here, and the table path reads
+ * them back if its own stdin was empty.
+ *
+ * Stale data is worse than missing data — if the saved snapshot is older
+ * than `maxAgeMs` the loader returns null and the table view stays quiet.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { userDataDir } from './paths.js';
+
+const CACHE_PATH = join(userDataDir(), 'last-caps.json');
+
+function ensureDir() {
+  const dir = userDataDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+export function persistCaps(caps) {
+  if (!caps) return;
+  try {
+    ensureDir();
+    const payload = { capturedAt: Date.now(), caps };
+    writeFileSync(CACHE_PATH, JSON.stringify(payload) + '\n');
+  } catch {
+    // best-effort cache, never blocks the statusline
+  }
+}
+
+/**
+ * @param {object} [opts]
+ * @param {number} [opts.maxAgeMs=5*60*1000] - drop snapshots older than this.
+ * @returns {object|null}
+ */
+export function loadRecentCaps({ maxAgeMs = 5 * 60 * 1000 } = {}) {
+  try {
+    if (!existsSync(CACHE_PATH)) return null;
+    const raw = readFileSync(CACHE_PATH, 'utf8');
+    const data = JSON.parse(raw);
+    if (!data || !data.caps) return null;
+    if (typeof data.capturedAt !== 'number') return null;
+    if (Date.now() - data.capturedAt > maxAgeMs) return null;
+    return data.caps;
+  } catch {
+    return null;
+  }
+}

package/src/formatters/statusline.js

@@ -49,6 +49,39 @@ function formatTimer(remainingSec) {
   return `${m}:${String(s).padStart(2, '0')}`;
 }
 
+/**
+ * Pick the cap-warn chip ({ kind, usedPct, resetsAt, label }) that should
+ * surface, or null if neither window is at 90%+. When both windows are warning,
+ * the one that resets sooner wins (it's the more imminent block).
+ */
+export function pickCapWarn(caps) {
+  if (!caps) return null;
+  const candidates = [];
+  if (caps.fiveHour && caps.fiveHour.usedPct >= 90) {
+    candidates.push({
+      kind: 'five_hour',
+      label: '5H',
+      usedPct: caps.fiveHour.usedPct,
+      resetsAt: caps.fiveHour.resetsAt,
+    });
+  }
+  if (caps.sevenDay && caps.sevenDay.usedPct >= 90) {
+    candidates.push({
+      kind: 'seven_day',
+      label: '7D',
+      usedPct: caps.sevenDay.usedPct,
+      resetsAt: caps.sevenDay.resetsAt,
+    });
+  }
+  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 +89,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, hit, ttl, saved, ctx, period. 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 } = data;
   const { hitRate } = summary;
 
   // Hit rate → color signal
@@ -170,12 +204,40 @@ 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;
 
+  // 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);
+    if (isIcon && verbose) {
+      capWarnSeg = `${c(BOLD)}${c(RED)}🚨 ${capWarn.label} cap ${pct}%${c(RESET)}`;
+    } else if (isIcon) {
+      capWarnSeg = `${c(BOLD)}${c(RED)}🚨 ${capWarn.label} ${pct}%${c(RESET)}`;
+    } else if (verbose) {
+      capWarnSeg = `${c(BOLD)}${c(RED)}${capWarn.label} cap ${pct}%${c(RESET)}`;
+    } else {
+      capWarnSeg = `${c(BOLD)}${c(RED)}${capWarn.label} ${pct}%${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);
   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 (want('hit')) segs.push(hitSeg);
+  if (want('ttl')) segs.push(ttlSeg);
+  if (want('saved')) segs.push(saveSeg);
+  if (ctxSeg && want('ctx')) segs.push(ctxSeg);
+  if (want('period')) segs.push(periodSeg);
   return segs.join(' · ');
 }

package/src/formatters/table.js

@@ -123,7 +123,42 @@ function renderSpikeSection(spikes, contextWindow) {
   return lines;
 }
 
-export function formatReport({ summary: sum, trend, ttl, anomalies, cost, options, spikeReport, contextWindow }) {
+function formatResetIn(resetsAt, now = new Date()) {
+  if (!Number.isFinite(resetsAt)) return null;
+  const remaining = Math.max(0, resetsAt - Math.floor(now.getTime() / 1000));
+  if (remaining <= 0) return '0m';
+  const h = Math.floor(remaining / 3600);
+  const m = Math.floor((remaining % 3600) / 60);
+  if (h > 0) return `${h}h ${m}m`;
+  return `${m}m`;
+}
+
+function renderCapWarnSection(caps) {
+  const warning = [];
+  if (caps.fiveHour && caps.fiveHour.usedPct >= 90) {
+    warning.push({ label: '5-hour window', info: caps.fiveHour });
+  }
+  if (caps.sevenDay && caps.sevenDay.usedPct >= 90) {
+    warning.push({ label: '7-day window', info: caps.sevenDay });
+  }
+  if (warning.length === 0) return [];
+  const lines = [];
+  lines.push('  🚨 Rate-limit cap is closing in');
+  lines.push(`  ${'─'.repeat(50)}`);
+  for (const { label, info } of warning) {
+    const reset = formatResetIn(info.resetsAt);
+    const tail = reset ? `, resets in ${reset}` : '';
+    lines.push(`  • ${label}: ${Math.round(info.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 +168,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,162 @@
+/**
+ * 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';
+
+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 formatResetIn(resetsAt, now = new Date()) {
+  if (!Number.isFinite(resetsAt)) return null;
+  const remaining = Math.max(0, resetsAt - Math.floor(now.getTime() / 1000));
+  if (remaining <= 0) return '0m';
+  const h = Math.floor(remaining / 3600);
+  const m = Math.floor((remaining % 3600) / 60);
+  if (h > 0) return `${h}h ${m}m`;
+  return `${m}m`;
+}
+
+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) {
+    const fmtRow = (label, info) => {
+      if (!info) return `- ${label}: (unknown — stdin had no rate-limit info)`;
+      const reset = formatResetIn(info.resetsAt, now);
+      const tail = reset ? `, resets in ${reset}` : '';
+      return `- ${label}: ${Math.round(info.usedPct)}%${tail}`;
+    };
+    lines.push(fmtRow('5-hour window', caps.fiveHour));
+    lines.push(fmtRow('7-day window', caps.sevenDay));
+  } 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] - { fiveHour, sevenDay } 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 };
+}

package/src/history.js

@@ -3,6 +3,11 @@
  * (none → warning, warning A → warning B, warning → none). One markdown file
  * per calendar day so users can pinpoint "when did this start" easily.
  *
+ * Each event is written bilingually: the canonical English line first, the
+ * Korean translation as an indented "└" continuation right below. The chip
+ * text itself stays as-is (its symbol+English is part of the UX surface), but
+ * the diagnostic detail and resolved-status verbs are translated.
+ *
  * Storage path is platform-aware (see paths.userDataDir):
  *   Windows: %APPDATA%\claude-token-saver\history\YYYY-MM-DD.md
  *   macOS:   ~/Library/Application Support/claude-token-saver/history/YYYY-MM-DD.md
@@ -53,14 +58,70 @@ function saveState(state) {
   writeFileSync(STATE_PATH, JSON.stringify(state) + '\n');
 }
 
-function appendDayLine(line, date = new Date()) {
+/**
+ * Map a chip's English label to its Korean equivalent.
+ * Returns the input unchanged if no mapping is registered (forward-compat
+ * with chips added in advice.js after this map was last updated).
+ */
+function chipKo(chip) {
+  if (!chip) return chip;
+  const map = {
+    '⚠ 1M ON': '⚠ 1M 컨텍스트 활성',
+    '⚠ Cache miss': '⚠ 캐시 미스',
+    '⚠ Rebuild churn': '⚠ 캐시 재빌드 빈발',
+    '⚠ Input spike': '⚠ 입력 급증',
+    '⚠ Output heavy': '⚠ 출력 과다',
+    '⚠ Call surge': '⚠ 호출 급증',
+    '⚠ 5m TTL': '⚠ 5분 TTL',
+    '⏳ Cache expires': '⏳ 캐시 만료 임박',
+    '💰 Cache saved': '💰 캐시 절약',
+    '🧠 Cache hit': '🧠 캐시 적중',
+  };
+  return map[chip] || chip;
+}
+
+/**
+ * Translate the diagnostic detail string to Korean. The detail is constructed
+ * in cli.js and follows two stable shapes:
+ *   "Context auto-promoted to 1M (max single-request {N}k tokens)"
+ *   "session {ID}: CODE_A, CODE_B"
+ * Anything else falls through unchanged.
+ */
+function detailKo(detail) {
+  if (!detail) return detail;
+  const m1 = detail.match(/^Context auto-promoted to 1M \(max single-request (\d+)k tokens\)$/);
+  if (m1) return `1M 컨텍스트 자동 활성 (단일 요청 최대 ${m1[1]}k 토큰)`;
+  const m2 = detail.match(/^session ([^:]+): (.+)$/);
+  if (m2) {
+    const codeKo = {
+      LOW_HIT_RATE: '캐시 적중률 낮음',
+      FREQUENT_CACHE_REBUILD: '캐시 재빌드 빈발',
+      OUTPUT_HEAVY: '출력 과다',
+      INPUT_SPIKE: '입력 급증',
+      CALL_SURGE: '호출 급증',
+      TTL_5M: '5분 TTL',
+    };
+    const codes = m2[2]
+      .split(',')
+      .map((c) => c.trim())
+      .map((c) => codeKo[c] || c)
+      .join(', ');
+    return `세션 ${m2[1]}: ${codes}`;
+  }
+  return detail;
+}
+
+function appendDayLine(en, ko, date = new Date()) {
   ensureDir(HISTORY_DIR);
   const path = join(HISTORY_DIR, `${ymd(date)}.md`);
+  const block = ko && ko !== en ? `${en}\n  └ ${ko}\n` : `${en}\n`;
   if (!existsSync(path)) {
-    writeFileSync(path, `# Token Monitor — ${ymd(date)}\n\n## Events\n${line}\n`);
+    const header = `# Token Monitor / 토큰 모니터 — ${ymd(date)}\n\n## Events / 이벤트\n`;
+    writeFileSync(path, header + block);
   } else {
     const existing = readFileSync(path, 'utf8');
-    writeFileSync(path, existing.endsWith('\n') ? existing + line + '\n' : existing + '\n' + line + '\n');
+    const sep = existing.endsWith('\n') ? '' : '\n';
+    writeFileSync(path, existing + sep + block);
   }
 }
 
@@ -77,16 +138,23 @@ export function recordChip(chip, contextHints = {}) {
 
   if (current === last) return false;
 
-  let line;
+  const detail = contextHints.detail || null;
+  const detailEn = detail ? `  — ${detail}` : '';
+  const detailKr = detail ? `  — ${detailKo(detail)}` : '';
+
+  let en, ko;
   if (current && !last) {
-    line = `- ${hms(now)} ${current}` + (contextHints.detail ? `  — ${contextHints.detail}` : '');
+    en = `- ${hms(now)} ${current}${detailEn}`;
+    ko = `${chipKo(current)}${detailKr}`;
   } else if (current && last) {
-    line = `- ${hms(now)} ${last} → ${current}` + (contextHints.detail ? `  — ${contextHints.detail}` : '');
+    en = `- ${hms(now)} ${last} → ${current}${detailEn}`;
+    ko = `${chipKo(last)} → ${chipKo(current)}${detailKr}`;
   } else {
     // current === null, last was something — warning resolved
-    line = `- ${hms(now)} ✓ resolved (was ${last})`;
+    en = `- ${hms(now)} ✓ resolved (was ${last})`;
+    ko = `✓ 해소됨 (이전: ${chipKo(last)})`;
   }
-  appendDayLine(line, now);
+  appendDayLine(en, ko, now);
   saveState({ chip: current, ts: now.toISOString() });
   return true;
 }
@@ -110,6 +178,73 @@ export function readRecent(days = 7) {
   return out;
 }
 
+/**
+ * Format "resets in Hh Mm" / "Mm" given a Unix-epoch resets_at value.
+ * Returns null when the input isn't a finite number.
+ */
+function formatResetIn(resetsAt, now = new Date()) {
+  if (!Number.isFinite(resetsAt)) return null;
+  const remainingSec = Math.max(0, resetsAt - Math.floor(now.getTime() / 1000));
+  if (remainingSec <= 0) return '0m';
+  const h = Math.floor(remainingSec / 3600);
+  const m = Math.floor((remainingSec % 3600) / 60);
+  if (h > 0) return `${h}h ${m}m`;
+  return `${m}m`;
+}
+
+/**
+ * Record entering or exiting the cap-warn (>=90%) zone for a rate-limit
+ * window. Each window (`five_hour`, `seven_day`) has its own dedup slot, so
+ * the daily file gets two transitions max per window per warning episode.
+ *
+ * @param {'five_hour'|'seven_day'} kind
+ * @param {{ usedPct: number, resetsAt: number|null } | null} info
+ * @returns {boolean} true when a line was appended
+ */
+export function recordCapTransition(kind, info) {
+  const state = loadState();
+  const slotKey = `cap_${kind}`;
+  const wasWarn = !!state[slotKey];
+  const isWarn = !!(info && Number.isFinite(info.usedPct) && info.usedPct >= 90);
+  if (wasWarn === isWarn) return false;
+
+  const now = new Date();
+  const labelEn = kind === 'five_hour' ? '5H' : '7D';
+  const labelKo = kind === 'five_hour' ? '5시간 윈도' : '7일 윈도';
+  let en;
+  let ko;
+  if (isWarn) {
+    const pct = Math.round(info.usedPct);
+    const reset = formatResetIn(info.resetsAt, now);
+    const tail = reset ? ` (resets in ${reset})` : '';
+    const tailKo = reset ? ` (리셋까지 ${reset})` : '';
+    en = `- ${hms(now)} 🚨 ${labelEn} ${pct}% cap warning${tail}`;
+    ko = `🚨 ${labelKo} ${pct}% 캡 경고${tailKo}`;
+  } else {
+    en = `- ${hms(now)} ✓ ${labelEn} cap warning resolved`;
+    ko = `✓ ${labelKo} 캡 경고 해소`;
+  }
+  appendDayLine(en, ko, now);
+  state[slotKey] = isWarn;
+  saveState(state);
+  return true;
+}
+
+/**
+ * Record a handoff write — invoked by the `handoff` subcommand so
+ * `claude-token-saver history` shows when work was backed up to a HANDOFF file.
+ *
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function recordHandoff(filePath) {
+  const now = new Date();
+  const en = `- ${hms(now)} 📝 handoff written: ${filePath}`;
+  const ko = `📝 핸드오프 백업 작성: ${filePath}`;
+  appendDayLine(en, ko, now);
+  return true;
+}
+
 /**
  * List all available history file dates (sorted newest first).
  */

package/src/installer.js

@@ -15,7 +15,7 @@ import { claudeUserDir } from './paths.js';
 
 const SKILL_BODY = `---
 name: claude-token-saver
-description: Use when the user mentions Claude Code token usage, prompt cache hit rate, TTL/expiry, the 1M context window, cache misses, output spikes, or anything in the statusline produced by claude-token-saver (chips like "⚠ 1M ON", "⚠ Input spike", "⚠ Cache miss", "⚠ 5m TTL", "⚠ Rebuild churn", "⚠ Output heavy", "⚠ Call surge", "⏳ Cache expires", "💰 Cache saved", "🧠 Cache hit"). Also use when they ask to view token-usage history or want to understand a warning they just saw.
+description: Use when the user mentions Claude Code token usage, prompt cache hit rate, TTL/expiry, the 1M context window, cache misses, output spikes, rate-limit caps (5h/7d), or anything in the statusline produced by claude-token-saver (chips like "🚨 5H 94%", "🚨 7D 92%", "⚠ 1M ON", "⚠ Input spike", "⚠ Cache miss", "⚠ 5m TTL", "⚠ Rebuild churn", "⚠ Output heavy", "⚠ Call surge", "⏳ Cache expires", "💰 Cache saved", "🧠 Cache hit"). Also use when they ask to view token-usage history, want to understand a warning they just saw, or want to back up work before a session cap with \`claude-token-saver handoff\`.
 ---
 
 # claude-token-saver — Claude Code Token Monitor
@@ -26,11 +26,14 @@ countdown, savings, and (when relevant) a leading warning chip.
 
 ## When this skill should activate
 
-- The user references any chip wording: \`⚠ 1M ON\`, \`⚠ Input spike\`,
-  \`⚠ Cache miss\`, \`⚠ 5m TTL\`, \`⚠ Rebuild churn\`, \`⚠ Output heavy\`,
-  \`⚠ Call surge\`.
+- The user references any chip wording: \`🚨 5H NN%\`, \`🚨 7D NN%\`,
+  \`⚠ 1M ON\`, \`⚠ Input spike\`, \`⚠ Cache miss\`, \`⚠ 5m TTL\`,
+  \`⚠ Rebuild churn\`, \`⚠ Output heavy\`, \`⚠ Call surge\`.
 - The user asks "why is my cache hit rate low", "what does this warning mean",
   "when did this start happening", or similar.
+- The user is approaching a rate-limit cap and wants to back up the current
+  work so a fresh session can continue (point them at
+  \`claude-token-saver handoff\`).
 - The user wants to see the token-usage history file or asks for a summary
   of recent warnings.
 
@@ -48,6 +51,8 @@ countdown, savings, and (when relevant) a leading warning chip.
 
    | Chip               | Likely cause                                          |
    | ------------------ | ----------------------------------------------------- |
+   | \`🚨 5H NN%\`       | 5-hour rate-limit window at NN% (>=90%). Cap is imminent. |
+   | \`🚨 7D NN%\`       | 7-day rate-limit window at NN% (>=90%). Pace yourself.   |
    | \`⚠ 1M ON\`         | Auto-promoted to 1M context (Opus 4.7+ Max default).  |
    | \`⚠ Input spike\`   | One request consumed >250k or >3× the recent p95.     |
    | \`⚠ Cache miss\`    | Cache hit rate dropped below ~70%.                    |
@@ -56,10 +61,12 @@ countdown, savings, and (when relevant) a leading warning chip.
    | \`⚠ Output heavy\`  | Output ratio dominates input — inspect long generations. |
    | \`⚠ Call surge\`    | Request count is well above baseline.                 |
 
-5. **Suggest the next action.** For 1M ON, mention
-   \`CLAUDE_CODE_DISABLE_1M_CONTEXT=1\`. For 5m TTL, point at the Max plan's
-   1h bucket. For input spike, suggest splitting the conversation or
-   compacting context.
+5. **Suggest the next action.** For \`🚨 5H/7D\` chips, recommend running
+   \`claude-token-saver handoff\` to back up the current work to a
+   \`HANDOFF-*.md\` file before the cap hits, then continue in a fresh
+   session. For 1M ON, mention \`CLAUDE_CODE_DISABLE_1M_CONTEXT=1\`. For
+   5m TTL, point at the Max plan's 1h bucket. For input spike, suggest
+   splitting the conversation or compacting context.
 
 ## Useful commands
 
@@ -67,6 +74,8 @@ countdown, savings, and (when relevant) a leading warning chip.
 - \`claude-token-saver --days 7\` — wider window.
 - \`claude-token-saver history\` — recent warning transitions per day.
 - \`claude-token-saver history --days 30\` — longer history.
+- \`claude-token-saver handoff\` — write a HANDOFF-*.md template in cwd
+  capturing git status + cap snapshot, so a fresh session can resume cleanly.
 - \`claude-token-saver mode\` — show statusline preferences.
 - \`claude-token-saver mode icon verbose 1d\` — change preferences.
 
@@ -90,18 +99,23 @@ quick read of their Claude Code token usage and any active warnings.
 Steps:
 
 1. Run \`claude-token-saver history --days 7\` and capture the output. This
-   prints recent warning transitions (timestamps + chip + short detail).
+   prints recent warning transitions (timestamps + chip + short detail),
+   including any \`🚨 5H NN%\` / \`🚨 7D NN%\` cap-warn entries and any
+   \`📝 handoff written: ...\` events.
 2. Run \`claude-token-saver --days 1\` and capture the output. This prints the
    full table view: TTL breakdown, cost impact, daily trend, and any active
-   spikes with recommended actions.
+   spikes with recommended actions. When a rate-limit cap is at >=90% the
+   table leads with a "🚨 Rate-limit cap is closing in" section.
 3. Summarize for the user:
    - **Active warnings** — list the most recent unresolved chip(s) with the
-     time they appeared.
+     time they appeared. Cap-warn (\`🚨 5H/7D NN%\`) outranks everything else.
    - **Today's pattern** — when warnings cluster in time, mention it.
-   - **Recommended action** — pick the highest-leverage suggestion from the
-     table report's "Recommended actions" section.
+   - **Recommended action** — for cap-warn, point at \`claude-token-saver
+     handoff\` so the user can back up state before the cap blocks them.
+     Otherwise pick the highest-leverage suggestion from the table report's
+     "Recommended actions" section.
 4. If the history is empty, say so plainly — no warnings means the cache has
-   been healthy in the configured window.
+   been healthy and no caps were close in the configured window.
 
 Keep the summary to ~10 lines. The user can re-run the underlying commands
 themselves for the full output.

package/examples/statusline-with-rz1989s.sh

@@ -1,52 +0,0 @@
-#!/bin/sh
-# Combine rz1989s/claude-code-statusline (rich layout: repo, cost, MCP, prayer times)
-# with claude-token-saver (cache hit rate, TTL countdown, 1M-context detection,
-# spike diagnosis). The two projects don't overlap — rz1989s runs first, our
-# cache chip is appended as the final segment.
-#
-# Install:
-#   1) Follow rz1989s install instructions so bash ~/.claude/statusline.sh works:
-#      https://github.com/rz1989s/claude-code-statusline
-#   2) npm install -g claude-token-saver   (or rely on npx — fallback below)
-#   3) Save this file as: ~/.claude/statusline-with-rz1989s.sh
-#      chmod +x ~/.claude/statusline-with-rz1989s.sh
-#   4) In ~/.claude/settings.json:
-#      {
-#        "statusLine": {
-#          "type": "command",
-#          "command": "bash ~/.claude/statusline-with-rz1989s.sh",
-#          "refreshInterval": 1
-#        }
-#      }
-#
-# refreshInterval: 1 keeps our TTL countdown ticking while you're idle.
-# Drop to 2 or 5 for lower local CPU if your rz1989s config does heavy work.
-
-# Claude Code sends the session JSON on stdin. Both tools want to read it,
-# so we buffer it and tee to each.
-input=$(cat)
-
-# --- 1) rz1989s layout (if installed) ---
-RZ_STATUSLINE="${CLAUDE_RZ_STATUSLINE:-$HOME/.claude/statusline.sh}"
-if [ -f "$RZ_STATUSLINE" ]; then
-  printf '%s' "$input" | bash "$RZ_STATUSLINE"
-  # Separator between the two tools. Dim pipe.
-  printf ' \033[90m|\033[00m '
-fi
-
-# --- 2) claude-token-saver ---
-# Pass --exclude-session so the current session's tool calls don't reset the
-# TTL countdown. The path comes from the session JSON if present.
-session_path=$(printf '%s' "$input" | sed -n 's/.*"path"[[:space:]]*:[[:space:]]*"\([^"]*\.jsonl\)".*/\1/p' | head -n1)
-exclude_flag=""
-if [ -n "$session_path" ]; then
-  exclude_flag="--exclude-session $session_path"
-fi
-
-if command -v claude-token-saver >/dev/null 2>&1; then
-  # shellcheck disable=SC2086
-  claude-token-saver --statusline --icon $exclude_flag 2>/dev/null || true
-else
-  # shellcheck disable=SC2086
-  npx --yes claude-token-saver@latest --statusline --icon $exclude_flag 2>/dev/null || true
-fi