claude-token-saver 2.2.0 → 2.6.0

package/README.md

@@ -12,7 +12,7 @@
 **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 install`** — one command writes a Claude Code Skill that auto-activates when you mention "cache hit rate" / "1M context" / "5H cap" — no slash command needed.
 - **`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.
 
@@ -208,11 +208,12 @@ One command wires up everything else this README mentions:
 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.
+This writes one file under your Claude user dir:
+- `~/.claude/skills/claude-token-saver/SKILL.md` — auto-activates whenever you mention chip wording ("⚠ 1M ON", "cache miss", "5H cap", etc.) or ask for a token report. Claude Code will then read `claude-token-saver last`, drill into history if needed, and explain the warning.
 
-Re-run with `--force` to overwrite. Install only one piece with `install --skill` or `install --command`.
+If you previously installed v2.5.x or earlier, `install` also removes the now-redundant legacy `~/.claude/commands/token-monitor.md` slash command — its workflow is fully absorbed into the skill (same behavior, triggered by intent rather than typing `/token-monitor`).
+
+Re-run with `--force` to overwrite the skill file.
 
 ## Warning history (`history`) — new in v2.1
 
@@ -242,6 +243,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:
@@ -268,7 +287,7 @@ That writes `./HANDOFF-YYYY-MM-DD-HHMM.md` in the current directory with:
   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.
+The handoff write is also recorded in history (`📝 handoff written: …`), so `claude-token-saver history` and the auto-skill show both the cap-warn and the backup event next to each other.
 
 ## Hook Setup
 

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 auto-trigger 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.
@@ -169,38 +329,31 @@ async function main() {
     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
+  // Subcommand: install — write the Claude Code auto-trigger skill so the
+  // user can just mention chip wording and Claude responds. v2.6.0 dropped
+  // the redundant /token-monitor slash command in favor of the skill alone;
+  // a legacy command file is removed automatically. Cross-platform.
+  //   claude-token-saver install              # install/update the skill
+  //   claude-token-saver install --force      # overwrite existing skill file
   if (args[0] === 'install') {
-    const { installSkill, installCommand, installAll } = await import('../src/installer.js');
+    const { 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);
+    const r = installAll({ force });
+    print('skill', r.skill);
+    if (r.legacy.action === 'removed') {
+      print('legacy /token-monitor', r.legacy);
+      console.log('  (consolidated into the skill — same workflow, triggered by intent)');
     }
     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.');
+    console.log('Open Claude Code in any directory and just mention:');
+    console.log('  "cache hit rate" / "1M context" / "5H cap" — the skill auto-activates.');
     if (!force) {
       console.log('');
-      console.log('Tip: re-run with --force to overwrite existing files.');
+      console.log('Tip: re-run with --force to overwrite the existing skill file.');
     }
     return;
   }
@@ -399,24 +552,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 table view (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
     }
@@ -450,15 +609,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.
+    // so `claude-token-saver history` and the auto-skill 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);
+      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 +656,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.6.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*.