claude-token-saver 2.0.2 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # claude-token-saver
 
-> **Renamed from `claude-cache-monitor` in v2.0.** The old name still works — `npm i claude-cache-monitor` now redirects here, and the `claude-cache-monitor` binary remains available as an alias. See [migration notes](#migration-from-claude-cache-monitor).
+> **Renamed from `claude-cache-monitor` in v2.0.** The old npm package is deprecated and points here. The `claude-cache-monitor` binary is gone — use `claude-token-saver` instead. See [migration notes](#migration-from-claude-cache-monitor).
 
 > 📺 **HNPulse Shorts** — 이 도구가 만들어진 배경 (캐시 TTL 1h→5m 변경 이슈):
 > **[▶ Watch the Short](https://www.youtube.com/shorts/oSx2sg935nI)** · [All HNPulse Shorts](https://www.youtube.com/@HNPulseKR/shorts)
@@ -9,6 +9,13 @@
 
 **Save tokens on Claude Code.** Catch the session that suddenly burned 10× your usual input, figure out *why*, and get a one-line remediation you can paste.
 
+**Why I built this.** I'm on the Max plan. On Opus 4.6 I never hit the *current-session* cap. After Opus 4.7 rolled out, I started hitting it on the same workflow — repeatedly. The official token statistics didn't match what I was actually feeling, and Claude Code's UI doesn't show prompt-cache health. This tool is what let me see *why*: low cache hit rate, 5m TTL writes that should have been 1h, 1M context auto-promoted in the background.
+
+v2.1 (2026-04) adds the workflow that follows the diagnosis:
+- **`claude-token-saver install`** — one command writes a Claude Code Skill (auto-activates when you mention "cache hit rate" / "1M context" / etc.) and a `/token-monitor` slash command.
+- **`claude-token-saver history`** — every warning chip transition is auto-logged to a daily Markdown file, so you can answer "when did this start" without grepping logs.
+- **Cross-platform paths** — Windows (`%APPDATA%`), macOS (`~/Library/Application Support`), Linux (`~/.config` / XDG) all handled.
+
 v1.5 adds three things on top of the original `claude-cache-monitor`:
 - **Spike diagnosis** — detect recent sessions whose input tokens exploded vs. your own baseline, and name the cause (1M context, 5m TTL churn, cache rebuild, chatty output).
 - **1M-context detection** — Opus 4.7+ auto-enables 1M context on Max plans, silently. This tool surfaces it on the statusline as `Ctx 1M` (red) vs. `Ctx 200k` (green), with the OS-specific command to turn it off.
@@ -47,6 +54,12 @@ npx claude-token-saver --format json
 npx claude-token-saver --format csv
 ```
 
+> **Upgrading from `claude-cache-monitor`?** Uninstall the old package first, then install the new one and update your settings command name:
+> ```bash
+> npm uninstall -g claude-cache-monitor && npm i -g claude-token-saver
+> ```
+> After upgrading, change any `claude-cache-monitor …` invocations (including `statusLine.command` in `~/.claude/settings.json`) to `claude-token-saver …`. See [Migration](#migration-from-claude-cache-monitor).
+
 ## Spike Diagnosis (new in v1.5.0)
 
 When you run `npx claude-token-saver`, sessions from the last 24 hours whose total input tokens are **≥ 3× your p95 baseline** (or whose single-request context exceeds 250k, indicating 1M context) appear at the top of the report with root causes and remediation commands. Example output:
@@ -206,6 +219,48 @@ Claude Code calls this every ~300ms on events, plus once per `refreshInterval` s
 
 Statusline mode uses the last 7 days by default (override with `--days N`) and never emits multi-line errors, so your statusline stays clean even when there's no session data yet.
 
+## Claude Code integration (`install`) — new in v2.1
+
+One command wires up everything else this README mentions:
+
+```bash
+claude-token-saver install
+```
+
+This writes two files under your Claude user dir:
+- `~/.claude/skills/claude-token-saver/SKILL.md` — auto-activates whenever you mention chip wording ("⚠ 1M ON", "cache miss", etc.) or ask about token usage. Claude Code will then know to read history, drill into the table report, and explain the warning.
+- `~/.claude/commands/token-monitor.md` — adds a `/token-monitor` slash command that runs `claude-token-saver history` + a fresh report and summarizes both for you.
+
+Re-run with `--force` to overwrite. Install only one piece with `install --skill` or `install --command`.
+
+## Warning history (`history`) — new in v2.1
+
+The statusline path auto-logs every chip transition (none → ⚠, ⚠ A → ⚠ B, ⚠ → resolved) to a daily Markdown file. Read it back with:
+
+```bash
+claude-token-saver history             # last 7 days
+claude-token-saver history --days 30   # wider window
+claude-token-saver history --list      # just list available dates
+```
+
+Sample output:
+
+```
+# Token Monitor — 2026-04-25
+
+## Events
+- 09:14:02 ⚠ 1M ON  — Context auto-promoted to 1M (max single-request 280k tokens)
+- 09:42:18 ⚠ 1M ON → ⚠ Cache miss  — session abc12345: LOW_HIT_RATE
+- 10:05:47 ✓ resolved (was ⚠ Cache miss)
+```
+
+Storage paths (cross-platform):
+- **Windows**: `%APPDATA%\claude-token-saver\history\YYYY-MM-DD.md`
+- **macOS**: `~/Library/Application Support/claude-token-saver/history/YYYY-MM-DD.md`
+- **Linux**: `$XDG_CONFIG_HOME/claude-token-saver/history/YYYY-MM-DD.md` (or `~/.config/...`)
+
+Each day's file is plain Markdown — open it in any editor. Transitions are deduped, so the 1Hz statusline refresh doesn't spam.
+
 ## Hook Setup
 
 Automatically logs cache stats on every tool call and alerts when hit rate drops below a threshold.
@@ -342,24 +397,52 @@ Zero dependencies.
 
 ## Migration from claude-cache-monitor
 
-v2.0 renamed the package to reflect the expanded scope (spike diagnosis + 1M-context detection + remediation, not just cache monitoring). **No action required** in most cases:
+v2.0 renamed the package to reflect the expanded scope (spike diagnosis + 1M-context detection + remediation, not just cache monitoring).
+
+### New users
+
+```bash
+npm i -g claude-token-saver
+# or, no install:
+npx claude-token-saver
+```
+
+Skip the rest of this section.
 
-- `npm i claude-cache-monitor` still installs — the old package is deprecated and redirects here.
-- The binary `claude-cache-monitor` still works alongside the new `claude-token-saver` (both map to the same entry point).
-- Your existing `statusLine.command` setting in `~/.claude/settings.json` keeps working.
+### Upgrading from `claude-cache-monitor` v1.x
 
-If you want to update:
+Two steps:
 
 ```bash
+# 1. Remove the old package (its claude-cache-monitor bin is now obsolete).
 npm uninstall -g claude-cache-monitor
+
+# 2. Install the new one.
 npm i -g claude-token-saver
+```
+
+Then update any `claude-cache-monitor …` references. The main one is `statusLine.command` in `~/.claude/settings.json`:
+
+```jsonc
+// before
+"command": "claude-cache-monitor --statusline --icon"
+
+// after
+"command": "claude-token-saver --statusline --icon"
+```
 
-# then in ~/.claude/settings.json, change:
-#   "command": "claude-cache-monitor --statusline --icon"
-# to:
-#   "command": "claude-token-saver --statusline --icon"
+### Why we dropped the `claude-cache-monitor` bin alias
+
+Earlier v2.0 releases shipped a `claude-cache-monitor` bin alongside `claude-token-saver` so existing settings would keep working without edits. In practice this caused an `EEXIST: file already exists` error on `npm i -g claude-token-saver` when v1.x was still installed — and that collision forced the uninstall step anyway. Dropping the alias makes the upgrade path a clean two-liner and lets `npm i -g claude-token-saver` succeed directly if you've never installed the old one.
+
+### Zero-install (npx)
+
+```bash
+npx claude-token-saver@latest --statusline --icon
 ```
 
+No uninstall needed; npm just fetches the new name.
+
 ## License
 
 MIT

package/bin/cli.js

@@ -62,6 +62,113 @@ function hasFlag(name) {
 }
 
 async function main() {
+  // Subcommand: history — print recent warning transitions captured by the
+  // statusline. One markdown file per day, persisted under the platform-
+  // specific user-data dir.
+  //   claude-token-saver history              # last 7 days
+  //   claude-token-saver history --days 30    # custom window
+  //   claude-token-saver history --list       # just list available dates
+  if (args[0] === 'history') {
+    const { readRecent, listDates, historyDir } = await import('../src/history.js');
+    if (hasFlag('--list')) {
+      const dates = listDates();
+      if (dates.length === 0) {
+        console.log(`No history yet. Files will appear under: ${historyDir()}`);
+        return;
+      }
+      console.log(`History (${historyDir()}):`);
+      for (const d of dates) console.log(`  ${d}`);
+      return;
+    }
+    const days = parseFloat(getArg('--days') || '7');
+    const recent = readRecent(days);
+    if (recent.length === 0) {
+      console.log(`No warning history in the last ${days} day${days === 1 ? '' : 's'}.`);
+      console.log(`(Files would be written to: ${historyDir()})`);
+      return;
+    }
+    for (const { content } of recent) {
+      console.log(content.replace(/\n+$/, ''));
+      console.log('');
+    }
+    return;
+  }
+
+  // Subcommand: install — write the Claude Code Skill and slash command so
+  // /token-monitor and the auto-trigger skill become available without any
+  // manual file editing. Cross-platform (uses node:path + node:fs).
+  //   claude-token-saver install              # install both
+  //   claude-token-saver install --skill      # only the skill
+  //   claude-token-saver install --command    # only the slash command
+  //   claude-token-saver install --force      # overwrite existing files
+  if (args[0] === 'install') {
+    const { installSkill, installCommand, installAll } = await import('../src/installer.js');
+    const force = hasFlag('--force');
+    const onlySkill = hasFlag('--skill');
+    const onlyCommand = hasFlag('--command');
+    const print = (kind, r) => {
+      const verb = r.action === 'exists' ? 'already exists' : r.action;
+      console.log(`  ${kind}: ${r.path} (${verb})`);
+    };
+    if (onlySkill && !onlyCommand) {
+      print('skill', installSkill({ force }));
+    } else if (onlyCommand && !onlySkill) {
+      print('command', installCommand({ force }));
+    } else {
+      const r = installAll({ force });
+      print('skill', r.skill);
+      print('command', r.command);
+    }
+    console.log('');
+    console.log('Open Claude Code in any directory and try:');
+    console.log('  /token-monitor');
+    console.log('Or just mention "cache hit rate" / "1M context" — the skill auto-activates.');
+    if (!force) {
+      console.log('');
+      console.log('Tip: re-run with --force to overwrite existing files.');
+    }
+    return;
+  }
+
+  // Subcommand: mode — persist statusline preferences so future runs pick
+  // them up without flags or wrapper edits.
+  //   claude-token-saver mode                    # show current config
+  //   claude-token-saver mode icon verbose       # set icon + verbose
+  //   claude-token-saver mode reset              # clear back to defaults
+  if (args[0] === 'mode') {
+    const { applyMode, loadConfig, configPath, statuslineDefaults, VALID_KEYWORDS } =
+      await import('../src/config.js');
+    const words = args.slice(1);
+    if (words.length === 0) {
+      const eff = statuslineDefaults();
+      const raw = loadConfig().statusline || {};
+      console.log('Statusline mode (effective):');
+      console.log(`  icon:    ${eff.icon}`);
+      console.log(`  verbose: ${eff.verbose}`);
+      console.log(`  timer:   ${eff.timer}`);
+      console.log(`  color:   ${eff.color}`);
+      console.log(`  window:  ${eff.windowLabel} (${eff.windowHours}h)`);
+      console.log('');
+      console.log(`Stored config (${configPath()}):`);
+      console.log(`  ${Object.keys(raw).length === 0 ? '(none — using defaults)' : JSON.stringify(raw)}`);
+      console.log('');
+      console.log('Change with: claude-token-saver mode <keywords...>');
+      console.log(`Keywords: ${VALID_KEYWORDS.join(', ')}`);
+      return;
+    }
+    const { applied, unknown } = applyMode(words);
+    if (unknown.length) {
+      console.error(`Unknown keyword${unknown.length > 1 ? 's' : ''}: ${unknown.join(', ')}`);
+      console.error(`Valid: ${VALID_KEYWORDS.join(', ')}`);
+      process.exit(1);
+    }
+    const eff = statuslineDefaults();
+    console.log(`Updated: ${applied.join(', ')}`);
+    console.log(`Now: icon=${eff.icon} verbose=${eff.verbose} timer=${eff.timer} color=${eff.color} window=${eff.windowLabel}`);
+    console.log('Statusline picks up the change on the next refresh (~1s).');
+    return;
+  }
+
   // Hook management
   if (hasFlag('--install-hook')) {
     const { installHook } = await import('../src/hook-manager.js');
@@ -85,10 +192,89 @@ async function main() {
   // Statusline mode shortcut
   const isStatusline = hasFlag('--statusline') || getArg('--format') === 'statusline';
 
+  // Demo mode — render synthetic warning-case data through the real
+  // formatter for screencasts/marketing GIFs. `--demo cycle` rotates through
+  // every scenario based on wall clock so a screen recorder picks them up.
+  const demoArg = getArg('--demo');
+
+  // `claude-token-saver --demo table` (no --statusline) — full table view
+  // with all six issue drill-downs at once, for marketing screencasts.
+  if (!isStatusline && demoArg === 'table') {
+    const { buildTableDemoData } = await import('../src/demo.js');
+    const { formatReport } = await import('../src/formatters/table.js');
+    const data = buildTableDemoData({ version: PKG_VERSION });
+    console.log(formatReport(data));
+    return;
+  }
+
+  if (isStatusline && demoArg) {
+    const { buildScenarioData, listScenarios } = await import('../src/demo.js');
+    const { statuslineDefaults } = await import('../src/config.js');
+    const cfg = statuslineDefaults();
+    const cycleSeconds = parseFloat(getArg('--demo-cycle-sec') || '3');
+    const data = buildScenarioData(demoArg, {
+      cycleSeconds,
+      windowHours: cfg.windowHours,
+      windowLabel: cfg.windowLabel,
+      days: cfg.windowHours / 24,
+      version: PKG_VERSION,
+    });
+    if (!data) {
+      const known = listScenarios().map((s) => s.name).concat(['cycle']).join(', ');
+      console.error(`Unknown demo scenario: ${demoArg}`);
+      console.error(`Valid: ${known}`);
+      process.exit(1);
+    }
+    const { formatReport } = await import('../src/formatters/statusline.js');
+    const isIcon = hasFlag('--icon')
+      ? true
+      : (hasFlag('--no-icon') || hasFlag('--text') ? false : cfg.icon);
+    const isVerbose = hasFlag('--verbose')
+      ? true
+      : (hasFlag('--no-verbose') || hasFlag('--compact') ? false : cfg.verbose);
+    const showTimer = hasFlag('--no-timer') ? false : cfg.timer;
+    const colorOk = !hasFlag('--no-color') && !process.env.NO_COLOR && cfg.color;
+    const out = formatReport(data, {
+      color: colorOk,
+      verbose: isVerbose,
+      timer: showTimer,
+      mode: isIcon ? 'icon' : 'text',
+    });
+    // For `cycle` mode, prefix with the scenario label so the screen recorder
+    // shows what the viewer is looking at (only when explicitly requested).
+    if (demoArg === 'cycle' && hasFlag('--demo-label')) {
+      const gray = colorOk ? '\x1b[90m' : '';
+      const reset = colorOk ? '\x1b[0m' : '';
+      console.log(`${gray}[${data._demoLabel}]${reset}  ${out}`);
+    } else {
+      console.log(out);
+    }
+    return;
+  }
+
   // Report generation
-  // Statusline default = 7 days (fast, called every ~300ms). Others = 30 days.
-  const defaultDays = isStatusline ? 7 : 30;
-  const days = parseInt(getArg('--days') || getArg('-d') || String(defaultDays), 10);
+  // Statusline window comes from persisted config — hours-precise so users
+  // can pick `1h` / `6h` etc, not just whole days. Other formats default to
+  // 30 days as before.
+  let windowHours = 30 * 24;
+  let windowLabel = '30d';
+  if (isStatusline) {
+    const { statuslineDefaults } = await import('../src/config.js');
+    const d = statuslineDefaults();
+    windowHours = d.windowHours;
+    windowLabel = d.windowLabel;
+  }
+  // CLI overrides: --hours wins over --days; both win over config.
+  const hoursArg = getArg('--hours');
+  const daysArg = getArg('--days') || getArg('-d');
+  if (hoursArg !== undefined) {
+    windowHours = parseFloat(hoursArg);
+    windowLabel = `${windowHours}h`;
+  } else if (daysArg !== undefined) {
+    windowHours = parseFloat(daysArg) * 24;
+    windowLabel = `${parseFloat(daysArg)}d`;
+  }
+  const days = windowHours / 24;
   const format = isStatusline ? 'statusline' : (getArg('--format') || getArg('-f') || 'table');
   const projectFilter = getArg('--project') || getArg('-p');
 
@@ -136,9 +322,11 @@ async function main() {
   // actionable right now. 1M context is always shown; otherwise only fire
   // if the most recent session actually appears in the spike list.
   let spikeChip = null;
+  let chipDetail = null;
   if (format === 'statusline') {
     if (contextWindow.size === '1M') {
       spikeChip = chipForIssues([], contextWindow);
+      chipDetail = `Context auto-promoted to 1M (max single-request ${Math.round(contextWindow.maxContext / 1000)}k tokens)`;
     } else {
       const recentSession = sessions
         .slice()
@@ -150,8 +338,21 @@ async function main() {
         const m = sessionMetrics(recentSession);
         const issues = diagnoseSession(m, spikeReport.baseline);
         spikeChip = chipForIssues(issues, contextWindow);
+        const titles = issues
+          .map((i) => i.code)
+          .slice(0, 2)
+          .join(', ');
+        chipDetail = `session ${recentSession.sessionId?.slice(0, 8) || ''}: ${titles}`;
       }
     }
+    // Persist transitions to ~/.config/claude-token-saver/history/YYYY-MM-DD.md
+    // so /token-monitor and `claude-token-saver history` can replay them.
+    try {
+      const { recordChip } = await import('../src/history.js');
+      recordChip(spikeChip, { detail: chipDetail });
+    } catch {
+      // history is non-critical — don't let it break the statusline render
+    }
   }
 
   // Last API activity feeds the statusline TTL countdown.
@@ -181,7 +382,7 @@ async function main() {
     ttl,
     anomalies,
     cost,
-    options: { days, version: PKG_VERSION },
+    options: { days, windowHours, windowLabel, version: PKG_VERSION },
     lastActivity,
     spikeReport,
     contextWindow,
@@ -197,13 +398,25 @@ async function main() {
     output = formatReport(data);
   } else if (format === 'statusline') {
     const { formatReport } = await import('../src/formatters/statusline.js');
-    const colorOk = !hasFlag('--no-color') && !process.env.NO_COLOR;
-    const mode = hasFlag('--icon') ? 'icon' : 'text';
+    const { statuslineDefaults } = await import('../src/config.js');
+    const cfg = statuslineDefaults();
+
+    // CLI flags take precedence; otherwise fall back to persisted config.
+    const isIcon = hasFlag('--icon')
+      ? true
+      : (hasFlag('--no-icon') || hasFlag('--text') ? false : cfg.icon);
+    const isVerbose = hasFlag('--verbose')
+      ? true
+      : (hasFlag('--no-verbose') || hasFlag('--compact') ? false : cfg.verbose);
+    const showTimer = hasFlag('--no-timer') ? false : cfg.timer;
+    const colorOk =
+      !hasFlag('--no-color') && !process.env.NO_COLOR && cfg.color;
+
     output = formatReport(data, {
       color: colorOk,
-      verbose: hasFlag('--verbose'),
-      timer: !hasFlag('--no-timer'),
-      mode,
+      verbose: isVerbose,
+      timer: showTimer,
+      mode: isIcon ? 'icon' : 'text',
     });
   } else {
     const { formatReport } = await import('../src/formatters/table.js');

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "claude-token-saver",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {
-    "claude-token-saver": "./bin/cli.js",
-    "claude-cache-monitor": "./bin/cli.js"
+    "claude-token-saver": "./bin/cli.js"
   },
   "files": [
     "bin/",

package/src/advice.js

@@ -28,94 +28,99 @@ function toggleShortcut() {
 
 export const ISSUE_MESSAGES = {
   LARGE_INPUT_PER_REQUEST: {
-    title: '요청당 입력 토큰이 평소보다 매우 큽니다 (1M 컨텍스트 의심)',
+    title: 'Per-request input tokens are unusually large (1M context suspected)',
     explain:
-      'Opus 4.7부터 1M 컨텍스트가 표준 가격으로 풀리면서 Max 플랜은 자동으로 1M로 승격됩니다. ' +
-      '한 번 컨텍스트가 200k를 넘으면 long-context 단가가 적용되고 캐시 재사용도 어려워집니다.',
+      '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.',
     actions: () => [
       {
-        label: '1M 컨텍스트 OFF (환경변수)',
+        label: 'Disable 1M context (env var)',
         commands: disable1mEnvSnippet(),
       },
       {
-        label: '세션 내 토글',
-        commands: [`단축키 ${toggleShortcut()} 로 즉시 On/Off`],
+        label: 'In-session toggle',
+        commands: [`Press ${toggleShortcut()} to toggle on/off instantly`],
       },
       {
-        label: '⚠ 알려진 버그 #31640',
+        label: '⚠ Known bug #31640',
         commands: [
-          '/model 로 200k 선택해도 컨텍스트가 1M에 머무는 케이스가 있습니다.',
-          '확실히 끄려면 위 환경변수를 설정한 뒤 Claude Code를 재시작하세요.',
+          '/model 200k selection sometimes does not stick — context stays at 1M.',
+          'To force off: set the env var above and restart Claude Code.',
         ],
       },
     ],
   },
   LOW_HIT_RATE: {
-    title: '캐시 히트율이 낮습니다',
+    title: 'Cache hit rate is low',
     explain:
-      '캐시 히트율이 떨어지면 같은 프롬프트 prefix를 매번 다시 작성하게 되어 입력 비용이 커집니다.',
+      'A low hit rate means the same prompt prefix is being rewritten on every call, ' +
+      'inflating input cost.',
     actions: () => [
       {
-        label: '세션을 너무 자주 새로 열지 않았는지 확인',
-        commands: ['한 작업은 같은 세션에서 이어가세요 (컨텍스트 전환 = 캐시 미스)'],
+        label: 'Avoid opening fresh sessions too often',
+        commands: ['Continue the same task in the same session (context switching = cache miss)'],
       },
       {
-        label: '프롬프트 prefix 안정화',
-        commands: ['시스템 프롬프트·도구 정의가 요청마다 바뀌면 캐시가 매번 무효화됩니다'],
+        label: 'Stabilize the prompt prefix',
+        commands: ['System prompts / tool definitions that change per request invalidate the cache every time'],
       },
     ],
   },
   BUCKET_5M_DOMINANT: {
-    title: '5분 TTL 쓰기가 대부분입니다',
+    title: 'Most cache writes are landing in the 5-minute TTL bucket',
     explain:
-      'Pro 플랜은 5분 TTL로 고정됩니다. 5분 이상 간격이 벌어지면 캐시가 만료되어 재작성 비용이 발생합니다.',
+      'Pro plan is locked to 5m TTL. Gaps longer than 5 minutes expire the cache and force ' +
+      'a costly rebuild.',
     actions: () => [
       {
-        label: '5분 규칙',
+        label: 'The 5-minute rule',
         commands: [
-          '5분 안에 아무 프롬프트라도 보내면 prefix 캐시가 유지됩니다',
-          '긴 작업이 필요하면 Max 플랜으로 1h TTL 자동 적용',
+          'Sending any prompt within 5 minutes keeps the prefix cache warm',
+          'Upgrade to Max for the 1h TTL bucket on long tasks',
         ],
       },
     ],
   },
   HIGH_OUTPUT_RATIO: {
-    title: 'Output 비중이 비정상적으로 높습니다',
+    title: 'Output share is abnormally high',
     explain:
-      'Output 토큰은 입력보다 5배 이상 비쌉니다. 에이전트가 장문을 반복 생성하지 않는지 확인하세요.',
+      'Output tokens are 5x+ pricier than input. Check whether the agent is regenerating ' +
+      'long content unnecessarily.',
     actions: () => [
       {
-        label: '출력 길이 제한',
+        label: 'Cap output length',
         commands: [
-          '불필요한 전체 파일 쓰기·재생성 지양 (Edit 툴 활용)',
-          '긴 문서·README 생성 요청을 스크립트화해서 줄이세요',
+          'Avoid full-file rewrites — prefer the Edit tool',
+          'Move long doc/README generation requests into scripts to shrink output',
         ],
       },
     ],
   },
   HIGH_REQUEST_COUNT: {
-    title: '세션의 API 호출 수가 평소의 3배 이상입니다',
+    title: 'API calls in this session are 3x+ the baseline',
     explain:
-      '툴 호출이 과도하거나 루프/재시도가 많으면 호출당 prefix 재전송으로 입력 비용이 폭증합니다.',
+      'Excessive tool calls or retry/loop patterns rebroadcast the prefix on every call, ' +
+      'spiking input cost.',
     actions: () => [
       {
-        label: '병렬/일괄 처리',
-        commands: ['독립적인 조사는 한 메시지에 여러 도구 호출로 묶으세요'],
+        label: 'Parallel / batch processing',
+        commands: ['Bundle independent investigations into one message with multiple tool calls'],
       },
       {
-        label: '루프 감지',
-        commands: ['같은 테스트·검색을 반복하는 에이전트 루프가 없는지 확인'],
+        label: 'Watch for loops',
+        commands: ['Check that the agent is not repeating the same test/search in a loop'],
       },
     ],
   },
   FREQUENT_CACHE_REBUILD: {
-    title: '캐시 쓰기가 읽기보다 많습니다',
+    title: 'Cache writes outweigh cache reads',
     explain:
-      '캐시를 만들고 재사용하지 못하고 있습니다. 세션이 자주 끊기거나 TTL이 만료된 후 새로 시작한 경우 흔합니다.',
+      'The cache is being created but not reused. Common when sessions are short-lived or ' +
+      'restarted after TTL expiry.',
     actions: () => [
       {
-        label: '세션 지속 시간 확인',
-        commands: ['한 작업은 같은 Claude Code 세션에서 이어가세요'],
+        label: 'Check session continuity',
+        commands: ['Continue one task in one Claude Code session'],
       },
     ],
   },
@@ -124,15 +129,17 @@ export const ISSUE_MESSAGES = {
 /**
  * For the statusline: the single most relevant short chip (1~2 words).
  * Priority reflects what a user can act on *right now*.
+ * Kept short and English-only — these ride along on a single-line statusline
+ * shown to a global audience.
  */
 export function chipForIssues(issues, contextWindow) {
-  if (contextWindow?.size === '1M') return '⚠ 1M컨텍스트';
+  if (contextWindow?.size === '1M') return '⚠ 1M ON';
   const codes = issues.map((i) => i.code);
-  if (codes.includes('LARGE_INPUT_PER_REQUEST')) return '⚠ 입력폭주';
+  if (codes.includes('LARGE_INPUT_PER_REQUEST')) return '⚠ Input spike';
   if (codes.includes('BUCKET_5M_DOMINANT')) return '⚠ 5m TTL';
-  if (codes.includes('LOW_HIT_RATE')) return '⚠ 캐시미스';
-  if (codes.includes('FREQUENT_CACHE_REBUILD')) return '⚠ 재작성';
-  if (codes.includes('HIGH_OUTPUT_RATIO')) return '⚠ 출력과다';
-  if (codes.includes('HIGH_REQUEST_COUNT')) return '⚠ 호출폭주';
+  if (codes.includes('LOW_HIT_RATE')) return '⚠ Cache miss';
+  if (codes.includes('FREQUENT_CACHE_REBUILD')) return '⚠ Rebuild churn';
+  if (codes.includes('HIGH_OUTPUT_RATIO')) return '⚠ Output heavy';
+  if (codes.includes('HIGH_REQUEST_COUNT')) return '⚠ Call surge';
   return null;
 }