claude-token-saver 2.0.3 → 2.2.0

package/src/history.js

@@ -0,0 +1,258 @@
+/**
+ * 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.
+ *
+ * Each event is written bilingually: the canonical English line first, the
+ * Korean translation as an indented "└" continuation right below. The chip
+ * text itself stays as-is (its symbol+English is part of the UX surface), but
+ * the diagnostic detail and resolved-status verbs are translated.
+ *
+ * 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');
+}
+
+/**
+ * Map a chip's English label to its Korean equivalent.
+ * Returns the input unchanged if no mapping is registered (forward-compat
+ * with chips added in advice.js after this map was last updated).
+ */
+function chipKo(chip) {
+  if (!chip) return chip;
+  const map = {
+    '⚠ 1M ON': '⚠ 1M 컨텍스트 활성',
+    '⚠ Cache miss': '⚠ 캐시 미스',
+    '⚠ Rebuild churn': '⚠ 캐시 재빌드 빈발',
+    '⚠ Input spike': '⚠ 입력 급증',
+    '⚠ Output heavy': '⚠ 출력 과다',
+    '⚠ Call surge': '⚠ 호출 급증',
+    '⚠ 5m TTL': '⚠ 5분 TTL',
+    '⏳ Cache expires': '⏳ 캐시 만료 임박',
+    '💰 Cache saved': '💰 캐시 절약',
+    '🧠 Cache hit': '🧠 캐시 적중',
+  };
+  return map[chip] || chip;
+}
+
+/**
+ * Translate the diagnostic detail string to Korean. The detail is constructed
+ * in cli.js and follows two stable shapes:
+ *   "Context auto-promoted to 1M (max single-request {N}k tokens)"
+ *   "session {ID}: CODE_A, CODE_B"
+ * Anything else falls through unchanged.
+ */
+function detailKo(detail) {
+  if (!detail) return detail;
+  const m1 = detail.match(/^Context auto-promoted to 1M \(max single-request (\d+)k tokens\)$/);
+  if (m1) return `1M 컨텍스트 자동 활성 (단일 요청 최대 ${m1[1]}k 토큰)`;
+  const m2 = detail.match(/^session ([^:]+): (.+)$/);
+  if (m2) {
+    const codeKo = {
+      LOW_HIT_RATE: '캐시 적중률 낮음',
+      FREQUENT_CACHE_REBUILD: '캐시 재빌드 빈발',
+      OUTPUT_HEAVY: '출력 과다',
+      INPUT_SPIKE: '입력 급증',
+      CALL_SURGE: '호출 급증',
+      TTL_5M: '5분 TTL',
+    };
+    const codes = m2[2]
+      .split(',')
+      .map((c) => c.trim())
+      .map((c) => codeKo[c] || c)
+      .join(', ');
+    return `세션 ${m2[1]}: ${codes}`;
+  }
+  return detail;
+}
+
+function appendDayLine(en, ko, date = new Date()) {
+  ensureDir(HISTORY_DIR);
+  const path = join(HISTORY_DIR, `${ymd(date)}.md`);
+  const block = ko && ko !== en ? `${en}\n  └ ${ko}\n` : `${en}\n`;
+  if (!existsSync(path)) {
+    const header = `# Token Monitor / 토큰 모니터 — ${ymd(date)}\n\n## Events / 이벤트\n`;
+    writeFileSync(path, header + block);
+  } else {
+    const existing = readFileSync(path, 'utf8');
+    const sep = existing.endsWith('\n') ? '' : '\n';
+    writeFileSync(path, existing + sep + block);
+  }
+}
+
+/**
+ * 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;
+
+  const detail = contextHints.detail || null;
+  const detailEn = detail ? `  — ${detail}` : '';
+  const detailKr = detail ? `  — ${detailKo(detail)}` : '';
+
+  let en, ko;
+  if (current && !last) {
+    en = `- ${hms(now)} ${current}${detailEn}`;
+    ko = `${chipKo(current)}${detailKr}`;
+  } else if (current && last) {
+    en = `- ${hms(now)} ${last} → ${current}${detailEn}`;
+    ko = `${chipKo(last)} → ${chipKo(current)}${detailKr}`;
+  } else {
+    // current === null, last was something — warning resolved
+    en = `- ${hms(now)} ✓ resolved (was ${last})`;
+    ko = `✓ 해소됨 (이전: ${chipKo(last)})`;
+  }
+  appendDayLine(en, ko, 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;
+}
+
+/**
+ * Format "resets in Hh Mm" / "Mm" given a Unix-epoch resets_at value.
+ * Returns null when the input isn't a finite number.
+ */
+function formatResetIn(resetsAt, now = new Date()) {
+  if (!Number.isFinite(resetsAt)) return null;
+  const remainingSec = Math.max(0, resetsAt - Math.floor(now.getTime() / 1000));
+  if (remainingSec <= 0) return '0m';
+  const h = Math.floor(remainingSec / 3600);
+  const m = Math.floor((remainingSec % 3600) / 60);
+  if (h > 0) return `${h}h ${m}m`;
+  return `${m}m`;
+}
+
+/**
+ * Record entering or exiting the cap-warn (>=90%) zone for a rate-limit
+ * window. Each window (`five_hour`, `seven_day`) has its own dedup slot, so
+ * the daily file gets two transitions max per window per warning episode.
+ *
+ * @param {'five_hour'|'seven_day'} kind
+ * @param {{ usedPct: number, resetsAt: number|null } | null} info
+ * @returns {boolean} true when a line was appended
+ */
+export function recordCapTransition(kind, info) {
+  const state = loadState();
+  const slotKey = `cap_${kind}`;
+  const wasWarn = !!state[slotKey];
+  const isWarn = !!(info && Number.isFinite(info.usedPct) && info.usedPct >= 90);
+  if (wasWarn === isWarn) return false;
+
+  const now = new Date();
+  const labelEn = kind === 'five_hour' ? '5H' : '7D';
+  const labelKo = kind === 'five_hour' ? '5시간 윈도' : '7일 윈도';
+  let en;
+  let ko;
+  if (isWarn) {
+    const pct = Math.round(info.usedPct);
+    const reset = formatResetIn(info.resetsAt, now);
+    const tail = reset ? ` (resets in ${reset})` : '';
+    const tailKo = reset ? ` (리셋까지 ${reset})` : '';
+    en = `- ${hms(now)} 🚨 ${labelEn} ${pct}% cap warning${tail}`;
+    ko = `🚨 ${labelKo} ${pct}% 캡 경고${tailKo}`;
+  } else {
+    en = `- ${hms(now)} ✓ ${labelEn} cap warning resolved`;
+    ko = `✓ ${labelKo} 캡 경고 해소`;
+  }
+  appendDayLine(en, ko, now);
+  state[slotKey] = isWarn;
+  saveState(state);
+  return true;
+}
+
+/**
+ * Record a handoff write — invoked by the `handoff` subcommand so
+ * `claude-token-saver history` shows when work was backed up to a HANDOFF file.
+ *
+ * @param {string} filePath
+ * @returns {boolean}
+ */
+export function recordHandoff(filePath) {
+  const now = new Date();
+  const en = `- ${hms(now)} 📝 handoff written: ${filePath}`;
+  const ko = `📝 핸드오프 백업 작성: ${filePath}`;
+  appendDayLine(en, ko, now);
+  return true;
+}
+
+/**
+ * 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,150 @@
+/**
+ * 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, rate-limit caps (5h/7d), or anything in the statusline produced by claude-token-saver (chips like "🚨 5H 94%", "🚨 7D 92%", "⚠ 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, want to understand a warning they just saw, or want to back up work before a session cap with \`claude-token-saver handoff\`.
+---
+
+# 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: \`🚨 5H NN%\`, \`🚨 7D NN%\`,
+  \`⚠ 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 is approaching a rate-limit cap and wants to back up the current
+  work so a fresh session can continue (point them at
+  \`claude-token-saver handoff\`).
+- 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                                          |
+   | ------------------ | ----------------------------------------------------- |
+   | \`🚨 5H NN%\`       | 5-hour rate-limit window at NN% (>=90%). Cap is imminent. |
+   | \`🚨 7D NN%\`       | 7-day rate-limit window at NN% (>=90%). Pace yourself.   |
+   | \`⚠ 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 \`🚨 5H/7D\` chips, recommend running
+   \`claude-token-saver handoff\` to back up the current work to a
+   \`HANDOFF-*.md\` file before the cap hits, then continue in a fresh
+   session. 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 handoff\` — write a HANDOFF-*.md template in cwd
+  capturing git status + cap snapshot, so a fresh session can resume cleanly.
+- \`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),
+   including any \`🚨 5H NN%\` / \`🚨 7D NN%\` cap-warn entries and any
+   \`📝 handoff written: ...\` events.
+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. When a rate-limit cap is at >=90% the
+   table leads with a "🚨 Rate-limit cap is closing in" section.
+3. Summarize for the user:
+   - **Active warnings** — list the most recent unresolved chip(s) with the
+     time they appeared. Cap-warn (\`🚨 5H/7D NN%\`) outranks everything else.
+   - **Today's pattern** — when warnings cluster in time, mention it.
+   - **Recommended action** — for cap-warn, point at \`claude-token-saver
+     handoff\` so the user can back up state before the cap blocks them.
+     Otherwise 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 and no caps were close 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 }),
+  };
+}

package/src/paths.js

@@ -0,0 +1,41 @@
+/**
+ * Cross-platform user-data path resolution.
+ *
+ * Order of precedence:
+ *   1. $XDG_CONFIG_HOME (explicit override, honored on every platform)
+ *   2. %APPDATA% on Windows (e.g. C:\Users\foo\AppData\Roaming)
+ *   3. ~/Library/Application Support on macOS
+ *   4. ~/.config on Linux / fallback
+ *
+ * All paths are joined via node:path so the OS-correct separator is used
+ * automatically. Callers are responsible for `mkdirSync(..., { recursive: true })`
+ * before writing — every helper here returns a path string only.
+ */
+
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+/**
+ * Returns the base directory for this tool's user-level data
+ * (config, history, last-chip state).
+ */
+export function userDataDir() {
+  if (process.env.XDG_CONFIG_HOME) {
+    return join(process.env.XDG_CONFIG_HOME, 'claude-token-saver');
+  }
+  if (process.platform === 'win32' && process.env.APPDATA) {
+    return join(process.env.APPDATA, 'claude-token-saver');
+  }
+  if (process.platform === 'darwin') {
+    return join(homedir(), 'Library', 'Application Support', 'claude-token-saver');
+  }
+  return join(homedir(), '.config', 'claude-token-saver');
+}
+
+/**
+ * Returns the user's Claude Code config root (~/.claude on every OS Claude
+ * Code supports — the CLI itself uses this path on Windows and macOS too).
+ */
+export function claudeUserDir() {
+  return join(homedir(), '.claude');
+}

package/examples/statusline-with-rz1989s.sh

@@ -1,52 +0,0 @@
-#!/bin/sh
-# Combine rz1989s/claude-code-statusline (rich layout: repo, cost, MCP, prayer times)
-# with claude-token-saver (cache hit rate, TTL countdown, 1M-context detection,
-# spike diagnosis). The two projects don't overlap — rz1989s runs first, our
-# cache chip is appended as the final segment.
-#
-# Install:
-#   1) Follow rz1989s install instructions so bash ~/.claude/statusline.sh works:
-#      https://github.com/rz1989s/claude-code-statusline
-#   2) npm install -g claude-token-saver   (or rely on npx — fallback below)
-#   3) Save this file as: ~/.claude/statusline-with-rz1989s.sh
-#      chmod +x ~/.claude/statusline-with-rz1989s.sh
-#   4) In ~/.claude/settings.json:
-#      {
-#        "statusLine": {
-#          "type": "command",
-#          "command": "bash ~/.claude/statusline-with-rz1989s.sh",
-#          "refreshInterval": 1
-#        }
-#      }
-#
-# refreshInterval: 1 keeps our TTL countdown ticking while you're idle.
-# Drop to 2 or 5 for lower local CPU if your rz1989s config does heavy work.
-
-# Claude Code sends the session JSON on stdin. Both tools want to read it,
-# so we buffer it and tee to each.
-input=$(cat)
-
-# --- 1) rz1989s layout (if installed) ---
-RZ_STATUSLINE="${CLAUDE_RZ_STATUSLINE:-$HOME/.claude/statusline.sh}"
-if [ -f "$RZ_STATUSLINE" ]; then
-  printf '%s' "$input" | bash "$RZ_STATUSLINE"
-  # Separator between the two tools. Dim pipe.
-  printf ' \033[90m|\033[00m '
-fi
-
-# --- 2) claude-token-saver ---
-# Pass --exclude-session so the current session's tool calls don't reset the
-# TTL countdown. The path comes from the session JSON if present.
-session_path=$(printf '%s' "$input" | sed -n 's/.*"path"[[:space:]]*:[[:space:]]*"\([^"]*\.jsonl\)".*/\1/p' | head -n1)
-exclude_flag=""
-if [ -n "$session_path" ]; then
-  exclude_flag="--exclude-session $session_path"
-fi
-
-if command -v claude-token-saver >/dev/null 2>&1; then
-  # shellcheck disable=SC2086
-  claude-token-saver --statusline --icon $exclude_flag 2>/dev/null || true
-else
-  # shellcheck disable=SC2086
-  npx --yes claude-token-saver@latest --statusline --icon $exclude_flag 2>/dev/null || true
-fi