claude-token-saver 2.2.0 → 2.5.0

package/README.md

@@ -242,6 +242,24 @@ 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:

package/bin/cli.js

@@ -39,6 +39,10 @@ import { dirname, join } from 'node:path';
  *       "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;
@@ -52,22 +56,34 @@ function readStdinJson() {
 }
 
 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,
+  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 {
-    fiveHour: pick(rl.five_hour),
-    sevenDay: pick(rl.seven_day),
-  };
+    });
+  }
+  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';
@@ -108,7 +124,151 @@ 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.
@@ -399,24 +559,30 @@ async function main() {
   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.
+  // 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);
-  if (isStatusline && caps) {
+  let model = extractModel(stdinJson);
+  if (isStatusline && (caps || model)) {
     try {
-      const { persistCaps } = await import('../src/caps-cache.js');
-      persistCaps(caps);
+      const { persistSnapshot } = await import('../src/caps-cache.js');
+      persistSnapshot({ caps, model });
     } catch {
       // non-critical
     }
   }
-  if (!isStatusline && !caps) {
+  if (!isStatusline && (!caps || !model)) {
     try {
-      const { loadRecentCaps } = await import('../src/caps-cache.js');
-      caps = loadRecentCaps();
+      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
     }
@@ -456,9 +622,8 @@ async function main() {
       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);
+      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
@@ -498,6 +663,7 @@ async function main() {
     contextWindow,
     spikeChip,
     caps,
+    model,
   };
 
   let output;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "2.2.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": {

package/src/advice.js

@@ -26,106 +26,226 @@ function toggleShortcut() {
   return platformKind() === 'win' ? 'Alt + P' : '⌥ P (mac) / Alt + P (linux)';
 }
 
+/**
+ * Each entry has parallel English / Korean fields. table.js only reads the
+ * English fields (kept stable so the existing report layout doesn't shift).
+ * `last` (bin/cli.js) renders both, English first then `└ Korean` continuation
+ * — same bilingual style as the history.md file.
+ *
+ * `commandsKo` is optional per action: when a command is a literal code
+ * snippet (e.g. `export CLAUDE_CODE_DISABLE_1M_CONTEXT=1`), there's nothing
+ * to translate, so it's fine to omit and fall back to `commands`. When the
+ * command is descriptive prose, provide a Korean version.
+ */
 export const ISSUE_MESSAGES = {
   LARGE_INPUT_PER_REQUEST: {
     title: 'Per-request input tokens are unusually large (1M context suspected)',
+    titleKo: '요청당 입력 토큰이 비정상적으로 큼 (1M 컨텍스트 의심)',
     explain:
       'Since Opus 4.7, 1M context is priced at the standard rate, and Max plans auto-promote ' +
       'sessions to 1M. Once context goes past 200k, long-context pricing kicks in and cache reuse drops.',
+    explainKo:
+      'Opus 4.7부터 1M 컨텍스트가 표준 요금이 되었고, Max 플랜은 세션을 자동으로 1M으로 승격합니다. ' +
+      '200k를 넘는 순간 장기 컨텍스트 요금이 적용되며 캐시 재사용률도 떨어집니다.',
     actions: () => [
       {
         label: 'Disable 1M context (env var)',
+        labelKo: '1M 컨텍스트 끄기 (환경변수)',
         commands: disable1mEnvSnippet(),
       },
       {
         label: 'In-session toggle',
+        labelKo: '세션 내 즉시 토글',
         commands: [`Press ${toggleShortcut()} to toggle on/off instantly`],
+        commandsKo: [`${toggleShortcut()} 누르면 즉시 on/off 토글`],
       },
       {
         label: '⚠ Known bug #31640',
+        labelKo: '⚠ 알려진 버그 #31640',
         commands: [
           '/model 200k selection sometimes does not stick — context stays at 1M.',
           'To force off: set the env var above and restart Claude Code.',
         ],
+        commandsKo: [
+          '/model 200k 선택이 가끔 적용되지 않음 — 컨텍스트가 1M으로 유지됨.',
+          '강제로 끄려면 위의 환경변수를 설정하고 Claude Code를 재시작.',
+        ],
       },
     ],
   },
   LOW_HIT_RATE: {
     title: 'Cache hit rate is low',
+    titleKo: '캐시 적중률이 낮음',
     explain:
       'A low hit rate means the same prompt prefix is being rewritten on every call, ' +
       'inflating input cost.',
+    explainKo:
+      '적중률이 낮다는 건 동일한 프롬프트 prefix가 매 호출마다 다시 쓰이고 있다는 뜻이며, ' +
+      '입력 비용을 부풀립니다.',
     actions: () => [
       {
         label: 'Avoid opening fresh sessions too often',
+        labelKo: '새 세션을 너무 자주 열지 말기',
         commands: ['Continue the same task in the same session (context switching = cache miss)'],
+        commandsKo: ['같은 작업은 같은 세션에서 계속 (컨텍스트 전환 = 캐시 미스)'],
       },
       {
         label: 'Stabilize the prompt prefix',
+        labelKo: '프롬프트 prefix 안정화',
         commands: ['System prompts / tool definitions that change per request invalidate the cache every time'],
+        commandsKo: ['요청마다 바뀌는 시스템 프롬프트 / 도구 정의는 매번 캐시를 무효화'],
       },
     ],
   },
   BUCKET_5M_DOMINANT: {
     title: 'Most cache writes are landing in the 5-minute TTL bucket',
+    titleKo: '캐시 쓰기 대부분이 5분 TTL 버킷에 들어가고 있음',
     explain:
       'Pro plan is locked to 5m TTL. Gaps longer than 5 minutes expire the cache and force ' +
       'a costly rebuild.',
+    explainKo:
+      'Pro 플랜은 5분 TTL로 고정됩니다. 5분을 넘는 공백마다 캐시가 만료되고 비싼 재빌드가 강제됩니다.',
     actions: () => [
       {
         label: 'The 5-minute rule',
+        labelKo: '5분 규칙',
         commands: [
           'Sending any prompt within 5 minutes keeps the prefix cache warm',
           'Upgrade to Max for the 1h TTL bucket on long tasks',
         ],
+        commandsKo: [
+          '5분 이내 어떤 프롬프트든 보내면 prefix 캐시가 유지됨',
+          '긴 작업은 Max 플랜으로 업그레이드해서 1시간 TTL 버킷 사용',
+        ],
       },
     ],
   },
   HIGH_OUTPUT_RATIO: {
     title: 'Output share is abnormally high',
+    titleKo: '출력 비중이 비정상적으로 높음',
     explain:
       'Output tokens are 5x+ pricier than input. Check whether the agent is regenerating ' +
       'long content unnecessarily.',
+    explainKo:
+      '출력 토큰은 입력보다 5배 이상 비쌉니다. 에이전트가 불필요하게 긴 컨텐츠를 ' +
+      '반복 생성하고 있지 않은지 확인하세요.',
     actions: () => [
       {
         label: 'Cap output length',
+        labelKo: '출력 길이 줄이기',
         commands: [
           'Avoid full-file rewrites — prefer the Edit tool',
           'Move long doc/README generation requests into scripts to shrink output',
         ],
+        commandsKo: [
+          '파일 전체 재작성 피하기 — Edit 도구 우선 사용',
+          '긴 문서/README 생성 요청은 스크립트로 옮겨 출력 축소',
+        ],
       },
     ],
   },
   HIGH_REQUEST_COUNT: {
     title: 'API calls in this session are 3x+ the baseline',
+    titleKo: '이번 세션의 API 호출이 평소 대비 3배 이상',
     explain:
       'Excessive tool calls or retry/loop patterns rebroadcast the prefix on every call, ' +
       'spiking input cost.',
+    explainKo:
+      '과도한 도구 호출 또는 재시도/루프 패턴은 매 호출마다 prefix를 재전송해 입력 비용을 폭증시킵니다.',
     actions: () => [
       {
         label: 'Parallel / batch processing',
+        labelKo: '병렬 / 배치 처리',
         commands: ['Bundle independent investigations into one message with multiple tool calls'],
+        commandsKo: ['독립적인 조사 작업은 도구 호출 여러 개를 한 메시지로 묶어서 보내기'],
       },
       {
         label: 'Watch for loops',
+        labelKo: '루프 감시',
         commands: ['Check that the agent is not repeating the same test/search in a loop'],
+        commandsKo: ['에이전트가 동일한 테스트/검색을 루프로 반복하고 있지 않은지 확인'],
       },
     ],
   },
   FREQUENT_CACHE_REBUILD: {
     title: 'Cache writes outweigh cache reads',
+    titleKo: '캐시 쓰기가 읽기보다 많음',
     explain:
       'The cache is being created but not reused. Common when sessions are short-lived or ' +
       'restarted after TTL expiry.',
+    explainKo:
+      '캐시가 만들어지지만 재사용되지 않고 있습니다. 세션이 짧거나 TTL 만료 후 재시작될 때 흔합니다.',
     actions: () => [
       {
         label: 'Check session continuity',
+        labelKo: '세션 연속성 점검',
         commands: ['Continue one task in one Claude Code session'],
+        commandsKo: ['하나의 작업은 하나의 Claude Code 세션에서 계속'],
       },
     ],
   },
 };
 
+/**
+ * One-line action tips per issue code — bilingual. Used by history.js to
+ * inline a "what to do" hint right below each warning event in the daily
+ * markdown file, so the file alone is enough to answer "what was the warning,
+ * and how do I fix it" without re-running the tool.
+ *
+ * The full multi-step advice still lives in `ISSUE_MESSAGES[code].actions()`;
+ * `claude-token-saver last` prints that long form on demand.
+ */
+export const ISSUE_TIPS = {
+  LARGE_INPUT_PER_REQUEST: {
+    en: 'Disable 1M context: `export CLAUDE_CODE_DISABLE_1M_CONTEXT=1` (or ⌥P toggle)',
+    ko: '1M 컨텍스트 끄기: `export CLAUDE_CODE_DISABLE_1M_CONTEXT=1` (또는 ⌥P 토글)',
+  },
+  LOW_HIT_RATE: {
+    en: 'Continue same task in same session; keep prompt prefix stable',
+    ko: '같은 작업은 같은 세션에서 계속; 프롬프트 prefix 안정 유지',
+  },
+  BUCKET_5M_DOMINANT: {
+    en: 'Send any prompt within 5min to keep cache warm; Max plan unlocks 1h TTL',
+    ko: '5분 이내 한 번 더 보내 캐시 유지; Max 플랜은 1시간 TTL 제공',
+  },
+  HIGH_OUTPUT_RATIO: {
+    en: 'Avoid full-file rewrites — prefer Edit tool; move long generations to scripts',
+    ko: '파일 전체 재작성 피하기 — Edit 도구 사용; 긴 생성은 스크립트로',
+  },
+  HIGH_REQUEST_COUNT: {
+    en: 'Bundle independent calls into one message; check for retry loops',
+    ko: '독립 호출은 한 메시지에 묶기; 재시도 루프 점검',
+  },
+  FREQUENT_CACHE_REBUILD: {
+    en: 'Continue one task in one session — short sessions trigger rebuild',
+    ko: '한 작업은 한 세션에서 — 짧은 세션은 재빌드 유발',
+  },
+};
+
+/**
+ * Chip text → diagnostic codes. Some chips fire without a `detail` line that
+ * includes the code (e.g. `⚠ 1M ON`, which only carries context info), so we
+ * need a fallback so history.js can still surface the right tip.
+ */
+export const CHIP_TO_CODES = {
+  '⚠ 1M ON': ['LARGE_INPUT_PER_REQUEST'],
+  '⚠ Cache miss': ['LOW_HIT_RATE'],
+  '⚠ Input spike': ['LARGE_INPUT_PER_REQUEST'],
+  '⚠ 5m TTL': ['BUCKET_5M_DOMINANT'],
+  '⚠ Rebuild churn': ['FREQUENT_CACHE_REBUILD'],
+  '⚠ Output heavy': ['HIGH_OUTPUT_RATIO'],
+  '⚠ Call surge': ['HIGH_REQUEST_COUNT'],
+};
+
+/**
+ * Cap-warn (5h/7d >=90%) advice — bilingual. Always points at `handoff`
+ * because once the cap blocks you, you need a fresh session to continue.
+ */
+export const CAP_TIPS = {
+  en: 'Run `claude-token-saver handoff` to back up state before the cap blocks you',
+  ko: '`claude-token-saver handoff` 실행해서 캡 도달 전에 상태 백업',
+};
+
 /**
  * For the statusline: the single most relevant short chip (1~2 words).
  * Priority reflects what a user can act on *right now*.

package/src/caps-cache.js

@@ -1,9 +1,9 @@
 /**
- * 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.
+ * Statusline snapshot cache — the rate-limit numbers and model name 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 data. So
+ * whenever the statusline path sees them 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.
@@ -20,31 +20,64 @@ function ensureDir() {
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
 }
 
-export function persistCaps(caps) {
-  if (!caps) return;
+/**
+ * Persist whatever subset of statusline state we have right now. A null/empty
+ * snapshot is a no-op so callers don't have to guard.
+ *
+ * @param {{ caps?: object|null, model?: string|null }|null} snapshot
+ */
+export function persistSnapshot(snapshot) {
+  if (!snapshot) return;
+  const hasCaps = !!snapshot.caps;
+  const hasModel = typeof snapshot.model === 'string' && snapshot.model.length > 0;
+  if (!hasCaps && !hasModel) return;
   try {
     ensureDir();
-    const payload = { capturedAt: Date.now(), caps };
+    const payload = {
+      capturedAt: Date.now(),
+      caps: snapshot.caps || null,
+      model: snapshot.model || null,
+    };
     writeFileSync(CACHE_PATH, JSON.stringify(payload) + '\n');
   } catch {
     // best-effort cache, never blocks the statusline
   }
 }
 
+/**
+ * v2.3 wrote `caps` as `{ fiveHour, sevenDay }`; v2.4+ writes `{ windows: [...] }`.
+ * Convert on read so a returning user's stale snapshot still feeds the table view
+ * until the next statusline refresh overwrites it.
+ */
+function normalizeCaps(caps) {
+  if (!caps || typeof caps !== 'object') return null;
+  if (Array.isArray(caps.windows)) return caps;
+  const windows = [];
+  if (caps.fiveHour && typeof caps.fiveHour === 'object') {
+    windows.push({ key: 'five_hour', usedPct: caps.fiveHour.usedPct, resetsAt: caps.fiveHour.resetsAt ?? null });
+  }
+  if (caps.sevenDay && typeof caps.sevenDay === 'object') {
+    windows.push({ key: 'seven_day', usedPct: caps.sevenDay.usedPct, resetsAt: caps.sevenDay.resetsAt ?? null });
+  }
+  return windows.length ? { windows } : null;
+}
+
 /**
  * @param {object} [opts]
  * @param {number} [opts.maxAgeMs=5*60*1000] - drop snapshots older than this.
- * @returns {object|null}
+ * @returns {{ caps: object|null, model: string|null }|null}
  */
-export function loadRecentCaps({ maxAgeMs = 5 * 60 * 1000 } = {}) {
+export function loadRecentSnapshot({ 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 (!data || typeof data.capturedAt !== 'number') return null;
     if (Date.now() - data.capturedAt > maxAgeMs) return null;
-    return data.caps;
+    return {
+      caps: normalizeCaps(data.caps),
+      model: data.model || null,
+    };
   } catch {
     return null;
   }