claude-token-saver 2.0.3 → 2.2.0

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;
 }

package/src/caps-cache.js

@@ -0,0 +1,51 @@
+/**
+ * Caps cache — the rate-limit numbers only flow through stdin from Claude
+ * Code's statusline contract, but we want the table view (e.g. invoked by
+ * `/token-monitor`) to surface the same cap-warn box. So whenever the
+ * statusline path sees caps it writes them here, and the table path reads
+ * them back if its own stdin was empty.
+ *
+ * Stale data is worse than missing data — if the saved snapshot is older
+ * than `maxAgeMs` the loader returns null and the table view stays quiet.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { userDataDir } from './paths.js';
+
+const CACHE_PATH = join(userDataDir(), 'last-caps.json');
+
+function ensureDir() {
+  const dir = userDataDir();
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+export function persistCaps(caps) {
+  if (!caps) return;
+  try {
+    ensureDir();
+    const payload = { capturedAt: Date.now(), caps };
+    writeFileSync(CACHE_PATH, JSON.stringify(payload) + '\n');
+  } catch {
+    // best-effort cache, never blocks the statusline
+  }
+}
+
+/**
+ * @param {object} [opts]
+ * @param {number} [opts.maxAgeMs=5*60*1000] - drop snapshots older than this.
+ * @returns {object|null}
+ */
+export function loadRecentCaps({ maxAgeMs = 5 * 60 * 1000 } = {}) {
+  try {
+    if (!existsSync(CACHE_PATH)) return null;
+    const raw = readFileSync(CACHE_PATH, 'utf8');
+    const data = JSON.parse(raw);
+    if (!data || !data.caps) return null;
+    if (typeof data.capturedAt !== 'number') return null;
+    if (Date.now() - data.capturedAt > maxAgeMs) return null;
+    return data.caps;
+  } catch {
+    return null;
+  }
+}

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,
+  };
+}