claude-token-saver 2.0.3 → 2.1.0

package/src/demo.js

@@ -0,0 +1,251 @@
+/**
+ * Demo scenarios for the statusline — used for screencasts/marketing GIFs
+ * embedded in the GitHub README and npm page.
+ *
+ * Activated via:
+ *   claude-token-saver --statusline --demo healthy
+ *   claude-token-saver --statusline --demo cycle    # rotates every 3s
+ *
+ * Each scenario builds the same data shape the real pipeline produces, so
+ * it flows through formatReport() unchanged.
+ */
+
+const SCENARIOS = [
+  {
+    name: 'healthy',
+    label: '✅ Healthy baseline',
+    data: {
+      hitRate: 0.983,
+      pct1h: 0.95,
+      savings: 2123,
+      elapsedSec: 30,
+      contextSize: '200k',
+      spikeChip: null,
+    },
+  },
+  {
+    name: 'low-hit',
+    label: '⚠ Cache miss (low hit rate)',
+    data: {
+      hitRate: 0.55,
+      pct1h: 0.95,
+      savings: 240,
+      elapsedSec: 30,
+      contextSize: '200k',
+      spikeChip: '⚠ Cache miss',
+    },
+  },
+  {
+    name: 'ttl-warning',
+    label: '⚠ TTL nearly out (yellow)',
+    data: {
+      hitRate: 0.983,
+      pct1h: 0.95,
+      savings: 2123,
+      elapsedSec: 3000,         // ~10min remaining of 1h
+      contextSize: '200k',
+      spikeChip: null,
+    },
+  },
+  {
+    name: 'ttl-expiring',
+    label: '⚠ TTL almost expired (red)',
+    data: {
+      hitRate: 0.983,
+      pct1h: 0.95,
+      savings: 2123,
+      elapsedSec: 3360,         // ~4min remaining of 1h
+      contextSize: '200k',
+      spikeChip: null,
+    },
+  },
+  {
+    name: 'ttl-expired',
+    label: '⚠ TTL EXPIRED',
+    data: {
+      hitRate: 0.983,
+      pct1h: 0.95,
+      savings: 2123,
+      elapsedSec: 4000,         // past 1h
+      contextSize: '200k',
+      spikeChip: null,
+    },
+  },
+  {
+    name: '5m-bucket',
+    label: '⚠ 5m TTL dominant (Pro plan)',
+    data: {
+      hitRate: 0.92,
+      pct1h: 0.15,
+      pct5m: 0.85,
+      savings: 410,
+      elapsedSec: 60,
+      contextSize: '200k',
+      spikeChip: '⚠ 5m TTL',
+    },
+  },
+  {
+    name: 'ctx-1m',
+    label: '⚠ 1M context auto-on',
+    data: {
+      hitRate: 0.78,
+      pct1h: 0.92,
+      savings: 1340,
+      elapsedSec: 30,
+      contextSize: '1M',
+      spikeChip: '⚠ 1M ON',
+    },
+  },
+  {
+    name: 'spike-input',
+    label: '⚠ Input spike',
+    data: {
+      hitRate: 0.91,
+      pct1h: 0.95,
+      savings: 1820,
+      elapsedSec: 30,
+      contextSize: '200k',
+      spikeChip: '⚠ Input spike',
+    },
+  },
+  {
+    name: 'spike-rebuild',
+    label: '⚠ Cache rebuild churn',
+    data: {
+      hitRate: 0.62,
+      pct1h: 0.85,
+      savings: 220,
+      elapsedSec: 30,
+      contextSize: '200k',
+      spikeChip: '⚠ Rebuild churn',
+    },
+  },
+  {
+    name: 'spike-output',
+    label: '⚠ Output ratio high',
+    data: {
+      hitRate: 0.94,
+      pct1h: 0.95,
+      savings: 1450,
+      elapsedSec: 30,
+      contextSize: '200k',
+      spikeChip: '⚠ Output heavy',
+    },
+  },
+  {
+    name: 'spike-calls',
+    label: '⚠ Request count surge',
+    data: {
+      hitRate: 0.93,
+      pct1h: 0.92,
+      savings: 980,
+      elapsedSec: 30,
+      contextSize: '200k',
+      spikeChip: '⚠ Call surge',
+    },
+  },
+];
+
+export function listScenarios() {
+  return SCENARIOS.map((s) => ({ name: s.name, label: s.label }));
+}
+
+/**
+ * Synthetic spike-report data for `--demo table` — exercises every issue
+ * code so the drill-down section renders all six advice blocks. Used for
+ * marketing recordings of the table view.
+ */
+export function buildTableDemoData(options = {}) {
+  const issueCodes = [
+    'LARGE_INPUT_PER_REQUEST',
+    'LOW_HIT_RATE',
+    'BUCKET_5M_DOMINANT',
+    'HIGH_OUTPUT_RATIO',
+    'HIGH_REQUEST_COUNT',
+    'FREQUENT_CACHE_REBUILD',
+  ];
+
+  const spikes = issueCodes.map((code, i) => ({
+    metrics: {
+      sessionId: `demo${String(i).padStart(4, '0')}-aaaa-bbbb`,
+      projectDir: ['ai-pipeline', 'frontend', 'data-eng', 'infra', 'docs-site', 'scratch'][i],
+      totalInput: [3_200_000, 850_000, 1_100_000, 620_000, 2_400_000, 740_000][i],
+      requestCount: [42, 128, 91, 67, 310, 58][i],
+      maxContextPerRequest: [280_000, 175_000, 195_000, 90_000, 145_000, 130_000][i],
+    },
+    ratio: [3.4, 2.1, 2.6, 1.9, 4.8, 2.3][i],
+    issues: [{ code }],
+  }));
+
+  return {
+    summary: {
+      sessions: 12,
+      apiCalls: 1247,
+      hitRate: 0.812,
+      totalInput: 9_540_000_000,
+    },
+    trend: [
+      { date: '2026-04-23', hitRate: 0.94, calls: 312, totalRead: 2.1e8, totalWrite: 8.2e6, pct5m: 0.08 },
+      { date: '2026-04-24', hitRate: 0.78, calls: 488, totalRead: 1.4e8, totalWrite: 1.5e7, pct5m: 0.42 },
+      { date: '2026-04-25', hitRate: 0.71, calls: 447, totalRead: 9.8e7, totalWrite: 2.1e7, pct5m: 0.61 },
+    ],
+    ttl: {
+      ephemeral5m: 1.5e7,
+      ephemeral1h: 2.4e7,
+      total: 3.9e7,
+      pct5m: 0.38,
+      pct1h: 0.62,
+    },
+    anomalies: [],
+    cost: {
+      tier: 'claude-opus-new',
+      actual: 487.32,
+      noCacheCost: 2143.91,
+      savings: 1656.59,
+      savingsRate: 0.773,
+      scenario5mCost: 612.04,
+      extraCostIf5m: 124.72,
+    },
+    options: {
+      days: options.days ?? 7,
+      windowHours: options.windowHours ?? 168,
+      windowLabel: options.windowLabel ?? '7d',
+      version: options.version ?? '',
+    },
+    spikeReport: { spikes, baseline: { p95: 940_000 } },
+    contextWindow: { size: '1M', maxContext: 280_000 },
+    lastActivity: Date.now() - 60 * 1000,
+    spikeChip: '⚠ 1M ON',
+  };
+}
+
+
+export function buildScenarioData(scenarioName, options) {
+  let scenario;
+  if (scenarioName === 'cycle') {
+    // Bucket Date.now() into N-second slots, rotate through scenarios.
+    const slot = Math.floor(Date.now() / (options.cycleSeconds * 1000)) % SCENARIOS.length;
+    scenario = SCENARIOS[slot];
+  } else {
+    scenario = SCENARIOS.find((s) => s.name === scenarioName);
+    if (!scenario) return null;
+  }
+
+  const { hitRate, pct1h, pct5m, savings, elapsedSec, contextSize, spikeChip } = scenario.data;
+  return {
+    summary: { hitRate },
+    ttl: { pct1h, pct5m: pct5m ?? (1 - pct1h) },
+    cost: { savings },
+    options: {
+      days: options.days ?? 1,
+      windowHours: options.windowHours ?? 24,
+      windowLabel: options.windowLabel ?? '1d',
+      version: options.version ?? '',
+    },
+    lastActivity: Date.now() - elapsedSec * 1000,
+    contextWindow: { size: contextSize },
+    spikeChip,
+    _demoLabel: scenario.label,
+    _demoName: scenario.name,
+  };
+}

package/src/formatters/statusline.js

@@ -87,25 +87,31 @@ export function formatReport(data, { color = true, verbose = false, timer = true
     : 'Cache hit';
   const hitSeg = `${c(BOLD)}${hitLabel}${c(RESET)} ${c(hitColor)}${formatPct(hitRate)}${c(RESET)}`;
 
-  //   text:       "Cost saved $1.5K"                |  same in verbose
-  //   icon:       "💰 $1.5K"                          |  verbose: "💰 Cost saved $1.5K"
+  //   text:       "Cache saved $1.5K"                |  same in verbose
+  //   icon:       "💰 $1.5K"                          |  verbose: "💰 Cache saved $1.5K"
   const saveLabel = isIcon
-    ? (verbose ? '💰 Cost saved' : '💰')
-    : 'Cost saved';
+    ? (verbose ? '💰 Cache saved' : '💰')
+    : 'Cache saved';
   const saveSeg = `${c(CYAN)}${saveLabel}${c(RESET)} ${formatMoney(savings)}`;
 
+  // Period label honors hour-precision configs (`mode 6h` → "6h", `mode 1d` → "1d").
+  // Fall back to legacy `${days}d` when callers haven't supplied a label.
+  const periodLabel = options.windowLabel || `${options.days}d`;
   const periodSeg = verbose
-    ? `${c(GRAY)}last ${options.days}d${c(RESET)}`
-    : `${c(GRAY)}${options.days}d${c(RESET)}`;
+    ? `${c(GRAY)}last ${periodLabel}${c(RESET)}`
+    : `${c(GRAY)}${periodLabel}${c(RESET)}`;
 
   // TTL countdown — how much time is left on the last API call's cache entry.
   // Matches Anthropic's actual prompt-cache behaviour: each call starts a fresh
   // TTL window, and the next call (hit) within that window resets it. So the
   // countdown visibly ticks down between prompts, and "resets" happens as a
   // jump back toward the bucket max the moment you send another message.
-  //   text compact:   "Expires 1h 59:58"
+  // Compact modes drop the bucket label — it's read as part of the clock
+  // ("1h 59:58" gets parsed as "1 hour 59 minutes 58 seconds"). The bucket
+  // is plan-determined and rarely changes, so verbose mode is where it belongs.
+  //   text compact:   "Expires 59:58"
   //   text verbose:   "1h bucket · expires in 59:58"
-  //   icon compact:   "⏳ 1h 59:58"
+  //   icon compact:   "⏳ 59:58"
   //   icon verbose:   "⏳ Expires 1h 59:58"
   let ttlSeg;
   if (timer && lastActivity) {
@@ -119,22 +125,28 @@ export function formatReport(data, { color = true, verbose = false, timer = true
       pct > 0.10 ? YELLOW :
       RED;
 
-    if (isIcon) {
-      const prefix = verbose ? '⏳ Expires ' : '⏳ ';
-      ttlSeg = `${c(bucketColor)}${prefix}${bucketLabel}${c(RESET)} ${c(timerColor)}${text}${c(RESET)}`;
+    if (isIcon && verbose) {
+      // Drop bucket here too — `⏳ Expires 1h 57:20` reads as "1h 57m 20s left"
+      // for the same reason the compact form did. The bucket lives in the
+      // text-verbose layout where the "bucket" word + `·` separator make it
+      // unambiguous.
+      ttlSeg = `${c(timerColor)}⏳ Cache expires ${text}${c(RESET)}`;
+    } else if (isIcon) {
+      ttlSeg = `${c(timerColor)}⏳ ${text}${c(RESET)}`;
     } else if (verbose) {
-      ttlSeg = `${c(bucketColor)}${bucketLabel} bucket${c(RESET)} · ${c(timerColor)}expires in ${text}${c(RESET)}`;
+      ttlSeg = `${c(bucketColor)}Cache ${bucketLabel} bucket${c(RESET)} · ${c(timerColor)}expires in ${text}${c(RESET)}`;
     } else {
-      ttlSeg = `${c(bucketColor)}Expires ${bucketLabel}${c(RESET)} ${c(timerColor)}${text}${c(RESET)}`;
+      ttlSeg = `${c(timerColor)}Cache expires ${text}${c(RESET)}`;
     }
   } else {
+    // No-timer fallback: only the bucket is available, so we show just that.
     if (isIcon) {
-      const prefix = verbose ? '⏳ Bucket ' : '⏳ ';
+      const prefix = verbose ? '⏳ Cache bucket ' : '⏳ ';
       ttlSeg = `${c(bucketColor)}${prefix}${bucketLabel}${c(RESET)}`;
     } else if (verbose) {
-      ttlSeg = `${c(bucketColor)}${bucketLabel} bucket${c(RESET)}`;
+      ttlSeg = `${c(bucketColor)}Cache ${bucketLabel} bucket${c(RESET)}`;
     } else {
-      ttlSeg = `${c(bucketColor)}Bucket ${bucketLabel}${c(RESET)}`;
+      ttlSeg = `${c(bucketColor)}Cache bucket ${bucketLabel}${c(RESET)}`;
     }
   }
 
@@ -144,7 +156,9 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   if (contextWindow && contextWindow.size && contextWindow.size !== 'unknown') {
     const label = contextWindow.size === '1M' ? '1M' : '200k';
     const ctxColor = contextWindow.size === '1M' ? RED : GREEN;
-    if (isIcon) {
+    if (isIcon && verbose) {
+      ctxSeg = `${c(ctxColor)}📦 Context ${label}${c(RESET)}`;
+    } else if (isIcon) {
       ctxSeg = `${c(ctxColor)}📦 ${label}${c(RESET)}`;
     } else if (verbose) {
       ctxSeg = `${c(ctxColor)}Context ${label}${c(RESET)}`;
@@ -156,9 +170,12 @@ 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;
 
-  const segs = [hitSeg, ttlSeg, saveSeg];
-  if (ctxSeg) segs.push(ctxSeg);
+  // Warning chip leads — a glance at the statusline catches "something's wrong"
+  // before parsing any numbers. Healthy states have no chip and look unchanged.
+  const segs = [];
   if (spikeSeg) segs.push(spikeSeg);
+  segs.push(hitSeg, ttlSeg, saveSeg);
+  if (ctxSeg) segs.push(ctxSeg);
   segs.push(periodSeg);
   return segs.join(' · ');
 }

package/src/formatters/table.js

@@ -64,11 +64,11 @@ function formatContextSize(n) {
 
 function renderSpikeSection(spikes, contextWindow) {
   const lines = [];
-  lines.push('  ⚠ 토큰 급증 감지');
+  lines.push('  ⚠ Token spike detected');
   lines.push(`  ${'─'.repeat(50)}`);
   if (contextWindow && contextWindow.size === '1M') {
     lines.push(
-      `  컨텍스트 모드 추정: 1M  (최근 단일 요청 최대 ${formatContextSize(contextWindow.maxContext)} 토큰)`,
+      `  Context mode: 1M  (max recent single-request input ${formatContextSize(contextWindow.maxContext)} tokens)`,
     );
     lines.push('');
   }
@@ -77,11 +77,11 @@ function renderSpikeSection(spikes, contextWindow) {
     const ratioLabel = spike.ratio ? `${spike.ratio.toFixed(1)}× p95` : 'single-request > 250k';
     lines.push(
       `  • ${shortSessionId(m.sessionId)} [${m.projectDir || 'unknown'}]  ` +
-        `총 입력 ${formatContextSize(m.totalInput)}  (${ratioLabel}, 요청 ${m.requestCount}회)`,
+        `total input ${formatContextSize(m.totalInput)}  (${ratioLabel}, ${m.requestCount} requests)`,
     );
     if (m.maxContextPerRequest > 0) {
       lines.push(
-        `      단일 요청 최대 컨텍스트: ${formatContextSize(m.maxContextPerRequest)} 토큰`,
+        `      max single-request context: ${formatContextSize(m.maxContextPerRequest)} tokens`,
       );
     }
     for (const issue of spike.issues) {
@@ -104,7 +104,7 @@ function renderSpikeSection(spikes, contextWindow) {
     }
   }
   if (uniqueIssues.length > 0) {
-    lines.push('  권장 액션');
+    lines.push('  Recommended actions');
     lines.push(`  ${'─'.repeat(50)}`);
     for (const issue of uniqueIssues) {
       const info = ISSUE_MESSAGES[issue.code];
@@ -128,7 +128,7 @@ export function formatReport({ summary: sum, trend, ttl, anomalies, cost, option
 
   // Header
   lines.push('');
-  lines.push(`  Claude 토큰 아껴쓰기 — Last ${options.days} days`);
+  lines.push(`  Claude Token Saver — Last ${options.days} day${options.days === 1 ? '' : 's'}`);
   lines.push(`  (claude-token-saver v${options.version || ''})`.trimEnd());
   lines.push(`  ${'═'.repeat(50)}`);
   lines.push('');
@@ -142,10 +142,10 @@ export function formatReport({ summary: sum, trend, ttl, anomalies, cost, option
   if (contextWindow && contextWindow.size !== 'unknown') {
     const note =
       contextWindow.size === '1M'
-        ? '⚠ 1M 컨텍스트 사용 중 (Opus 4.7+ Max 기본값). 필요 없으면 CLAUDE_CODE_DISABLE_1M_CONTEXT=1'
-        : '✓ 200k 컨텍스트 (표준)';
+        ? '⚠ 1M context active (Opus 4.7+ Max default). Disable with CLAUDE_CODE_DISABLE_1M_CONTEXT=1'
+        : '✓ 200k context (standard)';
     lines.push(`  Context window: ${contextWindow.size}  ${note}`);
-    lines.push(`  (최근 단일 요청 최대 ${formatContextSize(contextWindow.maxContext)} 토큰)`);
+    lines.push(`  (max recent single-request input ${formatContextSize(contextWindow.maxContext)} tokens)`);
     lines.push('');
   }
 

package/src/history.js

@@ -0,0 +1,123 @@
+/**
+ * Warning history — appends an entry whenever the active chip transitions
+ * (none → warning, warning A → warning B, warning → none). One markdown file
+ * per calendar day so users can pinpoint "when did this start" easily.
+ *
+ * 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
+ *   Linux:   ~/.config/claude-token-saver/history/YYYY-MM-DD.md
+ *
+ * State (last-seen chip, prevents duplicate appends every 1s refresh):
+ *   <userDataDir>/last-chip.json
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { userDataDir } from './paths.js';
+
+const BASE_DIR = userDataDir();
+const HISTORY_DIR = join(BASE_DIR, 'history');
+const STATE_PATH = join(BASE_DIR, 'last-chip.json');
+
+export function historyDir() {
+  return HISTORY_DIR;
+}
+
+function ensureDir(p) {
+  if (!existsSync(p)) mkdirSync(p, { recursive: true });
+}
+
+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 hms(d = new Date()) {
+  return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}`;
+}
+
+function loadState() {
+  try {
+    return JSON.parse(readFileSync(STATE_PATH, 'utf8'));
+  } catch {
+    return { chip: null, ts: null };
+  }
+}
+
+function saveState(state) {
+  ensureDir(BASE_DIR);
+  writeFileSync(STATE_PATH, JSON.stringify(state) + '\n');
+}
+
+function appendDayLine(line, date = new Date()) {
+  ensureDir(HISTORY_DIR);
+  const path = join(HISTORY_DIR, `${ymd(date)}.md`);
+  if (!existsSync(path)) {
+    writeFileSync(path, `# Token Monitor — ${ymd(date)}\n\n## Events\n${line}\n`);
+  } else {
+    const existing = readFileSync(path, 'utf8');
+    writeFileSync(path, existing.endsWith('\n') ? existing + line + '\n' : existing + '\n' + line + '\n');
+  }
+}
+
+/**
+ * Record a chip transition. Called from the statusline render path.
+ * Returns `true` if a transition was logged, `false` if duplicate (same chip
+ * as last call).
+ */
+export function recordChip(chip, contextHints = {}) {
+  const state = loadState();
+  const now = new Date();
+  const current = chip || null;
+  const last = state.chip || null;
+
+  if (current === last) return false;
+
+  let line;
+  if (current && !last) {
+    line = `- ${hms(now)} ${current}` + (contextHints.detail ? `  — ${contextHints.detail}` : '');
+  } else if (current && last) {
+    line = `- ${hms(now)} ${last} → ${current}` + (contextHints.detail ? `  — ${contextHints.detail}` : '');
+  } else {
+    // current === null, last was something — warning resolved
+    line = `- ${hms(now)} ✓ resolved (was ${last})`;
+  }
+  appendDayLine(line, now);
+  saveState({ chip: current, ts: now.toISOString() });
+  return true;
+}
+
+/**
+ * Read history files for the most recent N days (oldest first).
+ * Returns array of { date, content } — empty content for days with no file.
+ */
+export function readRecent(days = 7) {
+  ensureDir(HISTORY_DIR);
+  const out = [];
+  for (let i = days - 1; i >= 0; i--) {
+    const d = new Date();
+    d.setDate(d.getDate() - i);
+    const date = ymd(d);
+    const path = join(HISTORY_DIR, `${date}.md`);
+    if (existsSync(path)) {
+      out.push({ date, content: readFileSync(path, 'utf8') });
+    }
+  }
+  return out;
+}
+
+/**
+ * List all available history file dates (sorted newest first).
+ */
+export function listDates() {
+  ensureDir(HISTORY_DIR);
+  return readdirSync(HISTORY_DIR)
+    .filter((f) => /^\d{4}-\d{2}-\d{2}\.md$/.test(f))
+    .map((f) => f.replace(/\.md$/, ''))
+    .sort()
+    .reverse();
+}

package/src/installer.js

@@ -0,0 +1,136 @@
+/**
+ * Installs the Claude Code integration assets:
+ *   - Skill:  ~/.claude/skills/claude-token-saver/SKILL.md
+ *   - Slash:  ~/.claude/commands/token-monitor.md
+ *
+ * All paths are resolved with node:path so Windows backslashes and POSIX
+ * forward-slashes are both handled. Directories are created with
+ * `mkdirSync(..., { recursive: true })` which is a no-op if they already
+ * exist on every platform.
+ */
+
+import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+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.
+---
+
+# claude-token-saver — Claude Code Token Monitor
+
+This skill helps users interpret and act on the \`claude-token-saver\` statusline
+in Claude Code. The statusline updates every ~1s and shows cache health, TTL
+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 asks "why is my cache hit rate low", "what does this warning mean",
+  "when did this start happening", or similar.
+- The user wants to see the token-usage history file or asks for a summary
+  of recent warnings.
+
+## What to do
+
+1. **Identify the chip.** If the user pasted a statusline, pull out the leading
+   \`⚠ ...\` chip. That maps to a specific issue category.
+2. **Show recent history.** Run \`claude-token-saver history\` (default last 7
+   days) to see the chronology of warning transitions. Each entry is timestamped
+   and includes a short detail string.
+3. **Drill down on the live state.** Run \`claude-token-saver --days 1\` (or
+   another window) to render the full table view, which lists per-session
+   spikes and recommended actions.
+4. **Explain the warning** in plain language. Use the chip → cause table:
+
+   | Chip               | Likely cause                                          |
+   | ------------------ | ----------------------------------------------------- |
+   | \`⚠ 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%.                    |
+   | \`⚠ 5m TTL\`        | Most cache writes are 5-min ephemeral (Pro plan default). |
+   | \`⚠ Rebuild churn\` | Cache being re-written rapidly — prefix is unstable.  |
+   | \`⚠ 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.
+
+## Useful commands
+
+- \`claude-token-saver\` — full table report (default last 1 day).
+- \`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 mode\` — show statusline preferences.
+- \`claude-token-saver mode icon verbose 1d\` — change preferences.
+
+## Storage layout (for reference)
+
+History files live under the OS-appropriate user-data dir:
+- Windows: \`%APPDATA%\\claude-token-saver\\history\\YYYY-MM-DD.md\`
+- macOS:   \`~/Library/Application Support/claude-token-saver/history/YYYY-MM-DD.md\`
+- Linux:   \`~/.config/claude-token-saver/history/YYYY-MM-DD.md\`
+
+Each day's file is plain Markdown — safe to open in any editor.
+`;
+
+const COMMAND_BODY = `---
+description: Show recent claude-token-saver warning history and a fresh report.
+---
+
+You are responding to the \`/token-monitor\` slash command. The user wants a
+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).
+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.
+3. Summarize for the user:
+   - **Active warnings** — list the most recent unresolved chip(s) with the
+     time they appeared.
+   - **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.
+4. If the history is empty, say so plainly — no warnings means the cache has
+   been healthy in the configured window.
+
+Keep the summary to ~10 lines. The user can re-run the underlying commands
+themselves for the full output.
+`;
+
+function writeIfNeeded(file, body, force) {
+  const existed = existsSync(file);
+  if (existed && !force) return { path: file, action: 'exists' };
+  writeFileSync(file, body);
+  return { path: file, action: existed ? 'updated' : 'created' };
+}
+
+export function installSkill({ force = false } = {}) {
+  const dir = join(claudeUserDir(), 'skills', 'claude-token-saver');
+  const file = join(dir, 'SKILL.md');
+  mkdirSync(dir, { recursive: true });
+  return writeIfNeeded(file, SKILL_BODY, force);
+}
+
+export function installCommand({ force = false } = {}) {
+  const dir = join(claudeUserDir(), 'commands');
+  const file = join(dir, 'token-monitor.md');
+  mkdirSync(dir, { recursive: true });
+  return writeIfNeeded(file, COMMAND_BODY, force);
+}
+
+export function installAll({ force = false } = {}) {
+  return {
+    skill: installSkill({ force }),
+    command: installCommand({ force }),
+  };
+}