claude-token-saver 2.0.2 → 2.1.0

package/src/config.js

@@ -0,0 +1,151 @@
+/**
+ * User-level config persistence — keeps the user's preferred statusline mode
+ * across runs without forcing them to edit ~/.claude/settings.json or any
+ * wrapper script. CLI flags (e.g. --icon) still override what's stored here.
+ *
+ * Location is resolved per-platform by paths.userDataDir():
+ *   Windows: %APPDATA%\claude-token-saver\config.json
+ *   macOS:   ~/Library/Application Support/claude-token-saver/config.json
+ *   Linux:   $XDG_CONFIG_HOME/claude-token-saver/config.json or ~/.config/...
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { userDataDir } from './paths.js';
+
+const CONFIG_DIR = userDataDir();
+const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+
+export function configPath() {
+  return CONFIG_PATH;
+}
+
+export function loadConfig() {
+  try {
+    if (!existsSync(CONFIG_PATH)) return {};
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf8')) || {};
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(cfg) {
+  if (!existsSync(CONFIG_DIR)) mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(cfg, null, 2) + '\n');
+}
+
+// Each keyword maps to a single statusline option toggle.
+// Orthogonal — `mode icon verbose` flips both without resetting the rest.
+const KEYWORDS = {
+  icon:       { key: 'icon',    value: true  },
+  text:       { key: 'icon',    value: false },
+  verbose:    { key: 'verbose', value: true  },
+  compact:    { key: 'verbose', value: false },
+  timer:      { key: 'timer',   value: true  },
+  'no-timer': { key: 'timer',   value: false },
+  color:      { key: 'color',   value: true  },
+  'no-color': { key: 'color',   value: false },
+};
+
+// Window preset accepts forms like:
+//   `1h`, `6h`, `24h`        — hours
+//   `1d`, `7d`, `30d`        — days (× 24h)
+//   `days=14`, `hours=6`     — explicit
+// Returns hours (number) or null if not a window keyword.
+function parseWindow(word) {
+  const lower = String(word).toLowerCase();
+  const mh = lower.match(/^(\d+)h$/);
+  if (mh) return parseInt(mh[1], 10);
+  const md = lower.match(/^(\d+)d$/);
+  if (md) return parseInt(md[1], 10) * 24;
+  const eh = lower.match(/^hours?=(\d+)$/);
+  if (eh) return parseInt(eh[1], 10);
+  const ed = lower.match(/^days?=(\d+)$/);
+  if (ed) return parseInt(ed[1], 10) * 24;
+  return null;
+}
+
+export const VALID_KEYWORDS = Object.keys(KEYWORDS).concat([
+  '<N>h (e.g. 1h, 6h, 24h)',
+  '<N>d (e.g. 1d, 7d, 30d)',
+  'reset',
+  'default',
+]);
+
+/**
+ * Apply user-supplied mode keywords to the persisted config.
+ * Returns { applied, unknown } so the caller can report success/failure.
+ */
+export function applyMode(words) {
+  const cfg = loadConfig();
+  if (!cfg.statusline) cfg.statusline = {};
+
+  const applied = [];
+  const unknown = [];
+
+  for (const w of words) {
+    const lower = String(w).toLowerCase();
+    if (lower === 'reset' || lower === 'default') {
+      cfg.statusline = {};
+      applied.push(lower);
+      continue;
+    }
+    const hours = parseWindow(lower);
+    if (hours !== null && hours > 0) {
+      cfg.statusline.windowHours = hours;
+      // Drop legacy `days` field if present so a single source of truth wins.
+      delete cfg.statusline.days;
+      applied.push(formatWindow(hours));
+      continue;
+    }
+    const kw = KEYWORDS[lower];
+    if (!kw) {
+      unknown.push(w);
+      continue;
+    }
+    cfg.statusline[kw.key] = kw.value;
+    applied.push(lower);
+  }
+
+  if (applied.length && unknown.length === 0) saveConfig(cfg);
+  return { cfg, applied, unknown };
+}
+
+/**
+ * Effective statusline defaults, derived from the persisted config.
+ * Defaults for new users: icon=true, verbose=true, timer=true, color=true.
+ * Verbose+icon is the most readable preset (full labels + emoji anchors)
+ * and avoids the "1h bucket vs clock" ambiguity in compact mode.
+ * Users who explicitly opt out via `mode text` / `mode compact` get their
+ * choice persisted and respected.
+ */
+export function statuslineDefaults() {
+  const s = loadConfig().statusline || {};
+  // windowHours is the source of truth. Legacy `days` field still honored
+  // for users with old configs.
+  let windowHours;
+  if (Number.isFinite(s.windowHours) && s.windowHours > 0) {
+    windowHours = s.windowHours;
+  } else if (Number.isFinite(s.days) && s.days > 0) {
+    windowHours = s.days * 24;
+  } else {
+    windowHours = 24; // default: last 1 day
+  }
+  return {
+    icon:        s.icon    !== false,
+    verbose:     s.verbose !== false,
+    timer:       s.timer   !== false,
+    color:       s.color   !== false,
+    windowHours,
+    windowLabel: formatWindow(windowHours),
+  };
+}
+
+/**
+ * Render hours as the most natural unit:
+ *   24h → "1d", 168h → "7d", 6h → "6h", 36h → "36h" (not whole days).
+ */
+export function formatWindow(hours) {
+  if (hours >= 24 && hours % 24 === 0) return `${hours / 24}d`;
+  return `${hours}h`;
+}

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();
+}