claude-token-saver 2.2.0 → 2.6.0

package/src/handoff.js

@@ -16,6 +16,9 @@ import { writeFileSync, existsSync } from 'node:fs';
 import { execSync } from 'node:child_process';
 import { join, resolve } from 'node:path';
 
+import { formatResetIn, formatResetClock } from './format-time.js';
+import { labelForKey } from './window-labels.js';
+
 function pad(n) {
   return String(n).padStart(2, '0');
 }
@@ -52,16 +55,6 @@ function gitSnapshot(cwd) {
   return { branch, head, status };
 }
 
-function formatResetIn(resetsAt, now = new Date()) {
-  if (!Number.isFinite(resetsAt)) return null;
-  const remaining = Math.max(0, resetsAt - Math.floor(now.getTime() / 1000));
-  if (remaining <= 0) return '0m';
-  const h = Math.floor(remaining / 3600);
-  const m = Math.floor((remaining % 3600) / 60);
-  if (h > 0) return `${h}h ${m}m`;
-  return `${m}m`;
-}
-
 function pickPath(cwd, now) {
   const stem = `HANDOFF-${ymd(now)}-${hhmm(now)}`;
   const direct = join(cwd, `${stem}.md`);
@@ -99,15 +92,21 @@ function renderTemplate({ now, cwd, git, caps }) {
 
   lines.push('## Cap snapshot');
   lines.push('');
-  if (caps) {
-    const fmtRow = (label, info) => {
-      if (!info) return `- ${label}: (unknown — stdin had no rate-limit info)`;
-      const reset = formatResetIn(info.resetsAt, now);
-      const tail = reset ? `, resets in ${reset}` : '';
-      return `- ${label}: ${Math.round(info.usedPct)}%${tail}`;
-    };
-    lines.push(fmtRow('5-hour window', caps.fiveHour));
-    lines.push(fmtRow('7-day window', caps.sevenDay));
+  if (caps && Array.isArray(caps.windows) && caps.windows.length > 0) {
+    for (const win of caps.windows) {
+      const label = labelForKey(win.key).long;
+      if (!Number.isFinite(win.usedPct)) {
+        lines.push(`- ${label}: (unknown)`);
+        continue;
+      }
+      const reset = formatResetIn(win.resetsAt, now);
+      const clock = formatResetClock(win.resetsAt, now);
+      let tail = '';
+      if (reset && clock) tail = `, resets in ${reset} (at ${clock})`;
+      else if (reset) tail = `, resets in ${reset}`;
+      else if (clock) tail = `, resets at ${clock}`;
+      lines.push(`- ${label}: ${Math.round(win.usedPct)}%${tail}`);
+    }
   } else {
     lines.push('- (no cap data — run `handoff` from a Claude Code session for live numbers)');
   }
@@ -148,7 +147,7 @@ function renderTemplate({ now, cwd, git, caps }) {
  *
  * @param {object} [opts]
  * @param {string} [opts.cwd=process.cwd()]
- * @param {object|null} [opts.caps] - { fiveHour, sevenDay } from extractCaps
+ * @param {object|null} [opts.caps] - { windows: [...] } from extractCaps
  * @param {Date} [opts.now=new Date()]
  * @returns {{ path: string, git: { branch: string, head: string, status: string } | null }}
  */

package/src/history.js

@@ -20,6 +20,9 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { userDataDir } from './paths.js';
+import { formatResetIn, formatResetClock } from './format-time.js';
+import { labelForKey } from './window-labels.js';
+import { ISSUE_TIPS, CHIP_TO_CODES, CAP_TIPS } from './advice.js';
 
 const BASE_DIR = userDataDir();
 const HISTORY_DIR = join(BASE_DIR, 'history');
@@ -111,10 +114,56 @@ function detailKo(detail) {
   return detail;
 }
 
-function appendDayLine(en, ko, date = new Date()) {
+/**
+ * Resolve the diagnostic codes that apply to a transition. We try, in order:
+ *   1. `detail` of shape "session ID: CODE_A, CODE_B" (chip transitions with
+ *      explicit per-session codes — the richest source).
+ *   2. `chip` text mapped via CHIP_TO_CODES (covers 1M ON and chips that fire
+ *      without a per-session detail).
+ * Returns an array of unique codes, possibly empty.
+ */
+function codesForEvent(chip, detail) {
+  const out = [];
+  if (detail) {
+    const m = detail.match(/^session [^:]+:\s*(.+)$/);
+    if (m) {
+      for (const c of m[1].split(',').map((s) => s.trim()).filter(Boolean)) {
+        if (!out.includes(c)) out.push(c);
+      }
+    }
+  }
+  if (chip && CHIP_TO_CODES[chip]) {
+    for (const c of CHIP_TO_CODES[chip]) if (!out.includes(c)) out.push(c);
+  }
+  return out;
+}
+
+/**
+ * Build the "💡 ..." tip block for a given chip+detail pair. Returns
+ * { en: string, ko: string } where each may be empty if no tips apply
+ * (resolution events, unknown chips, etc.).
+ */
+function tipsForEvent(chip, detail) {
+  const codes = codesForEvent(chip, detail);
+  const enLines = [];
+  const koLines = [];
+  for (const code of codes) {
+    const tip = ISSUE_TIPS[code];
+    if (!tip) continue;
+    enLines.push(`  💡 ${tip.en}`);
+    koLines.push(`  💡 ${tip.ko}`);
+  }
+  return { en: enLines.join('\n'), ko: koLines.join('\n') };
+}
+
+function appendDayLine(en, ko, date = new Date(), tips = null) {
   ensureDir(HISTORY_DIR);
   const path = join(HISTORY_DIR, `${ymd(date)}.md`);
-  const block = ko && ko !== en ? `${en}\n  └ ${ko}\n` : `${en}\n`;
+  // Bilingual event line. Tip lines (when present) follow on their own lines so
+  // the file reads as: event-en / └ event-ko / 💡 tip-en / 💡 tip-ko.
+  let block = ko && ko !== en ? `${en}\n  └ ${ko}\n` : `${en}\n`;
+  if (tips && tips.en) block += `${tips.en}\n`;
+  if (tips && tips.ko) block += `${tips.ko}\n`;
   if (!existsSync(path)) {
     const header = `# Token Monitor / 토큰 모니터 — ${ymd(date)}\n\n## Events / 이벤트\n`;
     writeFileSync(path, header + block);
@@ -143,18 +192,23 @@ export function recordChip(chip, contextHints = {}) {
   const detailKr = detail ? `  — ${detailKo(detail)}` : '';
 
   let en, ko;
+  // Tips only on warning entry/transition (not resolution) — based on the
+  // *new* chip so users see how to handle what's currently active.
+  let tips = null;
   if (current && !last) {
     en = `- ${hms(now)} ${current}${detailEn}`;
     ko = `${chipKo(current)}${detailKr}`;
+    tips = tipsForEvent(current, detail);
   } else if (current && last) {
     en = `- ${hms(now)} ${last} → ${current}${detailEn}`;
     ko = `${chipKo(last)} → ${chipKo(current)}${detailKr}`;
+    tips = tipsForEvent(current, detail);
   } else {
     // current === null, last was something — warning resolved
     en = `- ${hms(now)} ✓ resolved (was ${last})`;
     ko = `✓ 해소됨 (이전: ${chipKo(last)})`;
   }
-  appendDayLine(en, ko, now);
+  appendDayLine(en, ko, now, tips);
   saveState({ chip: current, ts: now.toISOString() });
   return true;
 }
@@ -178,53 +232,64 @@ export function readRecent(days = 7) {
   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.
+ * window. Each window (keyed by its stdin name — e.g. `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
+ * @param {{ key: string, usedPct: number, resetsAt: number|null } | null} window
  * @returns {boolean} true when a line was appended
  */
-export function recordCapTransition(kind, info) {
+export function recordCapTransition(window) {
+  if (!window || typeof window.key !== 'string') return false;
   const state = loadState();
-  const slotKey = `cap_${kind}`;
+  const slotKey = `cap_${window.key}`;
   const wasWarn = !!state[slotKey];
-  const isWarn = !!(info && Number.isFinite(info.usedPct) && info.usedPct >= 90);
+  const isWarn = Number.isFinite(window.usedPct) && window.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일 윈도';
+  const labels = labelForKey(window.key);
+  const labelEn = labels.short;
+  // Korean labels map only the well-known windows; everything else falls back
+  // to the English short label (still readable for the bilingual line).
+  const KO_OVERRIDES = {
+    five_hour: '5시간 윈도',
+    seven_day: '7일 윈도',
+    seven_day_sonnet: '7일 윈도 (Sonnet)',
+    seven_day_opus: '7일 윈도 (Opus)',
+  };
+  const labelKo = KO_OVERRIDES[window.key] || labels.short;
   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})` : '';
+    const pct = Math.round(window.usedPct);
+    const reset = formatResetIn(window.resetsAt, now);
+    const clock = formatResetClock(window.resetsAt, now);
+    const tail = reset && clock
+      ? ` (resets in ${reset}, at ${clock})`
+      : reset
+        ? ` (resets in ${reset})`
+        : clock
+          ? ` (resets at ${clock})`
+          : '';
+    const tailKo = reset && clock
+      ? ` (${clock}에 리셋, 남은 ${reset})`
+      : reset
+        ? ` (리셋까지 ${reset})`
+        : clock
+          ? ` (${clock}에 리셋)`
+          : '';
     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);
+  // Cap-warn entry → handoff tip; resolution → no tip (just the ✓ line).
+  const capTips = isWarn ? { en: `  💡 ${CAP_TIPS.en}`, ko: `  💡 ${CAP_TIPS.ko}` } : null;
+  appendDayLine(en, ko, now, capTips);
   state[slotKey] = isWarn;
   saveState(state);
   return true;

package/src/installer.js

@@ -1,7 +1,11 @@
 /**
- * Installs the Claude Code integration assets:
+ * Installs the Claude Code integration asset:
  *   - Skill:  ~/.claude/skills/claude-token-saver/SKILL.md
- *   - Slash:  ~/.claude/commands/token-monitor.md
+ *
+ * v2.6.0 consolidates `/token-monitor` into the skill (was redundant with the
+ * auto-trigger). On install we actively remove a legacy
+ * ~/.claude/commands/token-monitor.md if present so users don't see two
+ * overlapping entry points.
  *
  * All paths are resolved with node:path so Windows backslashes and POSIX
  * forward-slashes are both handled. Directories are created with
@@ -9,7 +13,7 @@
  * exist on every platform.
  */
 
-import { writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { writeFileSync, mkdirSync, existsSync, unlinkSync } from 'node:fs';
 import { join } from 'node:path';
 import { claudeUserDir } from './paths.js';
 
@@ -36,18 +40,26 @@ countdown, savings, and (when relevant) a leading warning chip.
   \`claude-token-saver handoff\`).
 - The user wants to see the token-usage history file or asks for a summary
   of recent warnings.
+- The user asks for a quick token report or "current state" check (the
+  skill replaces the legacy \`/token-monitor\` slash command — same workflow,
+  triggered by intent rather than a typed slash).
 
 ## 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
+1. **Lead with the most recent warning + how to handle it.** Run
+   \`claude-token-saver last\` first. It returns the most recent warning event
+   (chip + detail + timestamp) plus the full advice block for it. Surface that
+   to the user before anything else — this is what they came for.
+2. **Identify the chip.** If the user pasted a statusline (instead of relying
+   on \`last\`), pull out the leading \`⚠ ...\` chip. That maps to a specific
+   issue category.
+3. **Show recent history.** Run \`claude-token-saver history\` (default last 7
+   days) to see the chronology of warning transitions. Each entry is timestamped,
+   bilingual (English line + 한국어), and includes a \`💡\` action tip inline.
+4. **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:
+5. **Explain the warning** in plain language. Use the chip → cause table:
 
    | Chip               | Likely cause                                          |
    | ------------------ | ----------------------------------------------------- |
@@ -61,7 +73,7 @@ countdown, savings, and (when relevant) a leading warning chip.
    | \`⚠ 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
+6. **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
@@ -70,9 +82,12 @@ countdown, savings, and (when relevant) a leading warning chip.
 
 ## Useful commands
 
+- \`claude-token-saver last\` — most recent warning + full advice (start here).
+- \`claude-token-saver last --days 7\` — widen the lookback window.
 - \`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\` — recent warning transitions per day, with
+  inline \`💡\` action tips.
 - \`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.
@@ -89,38 +104,6 @@ History files live under the OS-appropriate user-data dir:
 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' };
@@ -135,16 +118,18 @@ export function installSkill({ force = false } = {}) {
   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);
+// Removes the legacy /token-monitor slash command from prior versions.
+// v2.6.0 consolidated it into the skill — the file would otherwise linger.
+export function removeLegacyCommand() {
+  const file = join(claudeUserDir(), 'commands', 'token-monitor.md');
+  if (!existsSync(file)) return { path: file, action: 'absent' };
+  unlinkSync(file);
+  return { path: file, action: 'removed' };
 }
 
 export function installAll({ force = false } = {}) {
   return {
     skill: installSkill({ force }),
-    command: installCommand({ force }),
+    legacy: removeLegacyCommand(),
   };
 }

package/src/window-labels.js

@@ -0,0 +1,61 @@
+/**
+ * Friendly labels + icons for `rate_limits.*` keys from Claude Code's stdin
+ * payload. Known keys (`five_hour`, `seven_day`) get curated short/long labels
+ * and dedicated icons. Unknown keys are passed through with a derived label so
+ * any future window Anthropic adds (e.g. `seven_day_sonnet`) renders without
+ * a code change.
+ */
+
+// `short` is used by the cap-warn chip and history records (stable shape so
+// parsers/dedup keep working). `usageLabel` is the friendlier word that the
+// always-on usage segment renders next to the icon — empty string means the
+// icon alone carries the meaning (5H 'session/now' is the implicit default).
+const KNOWN = {
+  // ✦ reads as "AI token unit" (Anthropic/OpenAI/Gemini sparkle motif), more
+  // on-theme than the 🪙 coin which suggested in-app currency. Same width as
+  // 📅 in monospace terminals so the chip alignment stays stable.
+  // 'current' mirrors how `weekly` reads next to 7D — names the window in
+  // plain English so a glance at `✦ current ████▒░ 72%` tells the eye what's
+  // being measured without parsing the icon's meaning.
+  five_hour: { short: '5H', long: 'Current session', icon: '✦', usageLabel: 'current' },
+  seven_day: { short: '7D', long: 'Current week', icon: '📅', usageLabel: 'weekly' },
+  // Speculative — `/usage` shows a Sonnet-only weekly bucket, so if Anthropic
+  // ever surfaces it on stdin we render with a sensible default already.
+  seven_day_sonnet: { short: '7D-S', long: 'Current week (Sonnet)', icon: '🅂', usageLabel: 'weekly (Sonnet)' },
+  seven_day_opus: { short: '7D-O', long: 'Current week (Opus)', icon: '🅾', usageLabel: 'weekly (Opus)' },
+};
+
+function deriveShort(key) {
+  // "five_hour" → "5H"; "seven_day_sonnet" → "7DS"; arbitrary key → uppercase initials
+  const m = key.match(/^(\d+)_?([a-z]+)/);
+  if (m) {
+    const num = m[1];
+    const word = m[2];
+    const letter = word.charAt(0).toUpperCase();
+    const tail = key.slice(m[0].length);
+    const suffix = tail
+      .split('_')
+      .filter(Boolean)
+      .map((s) => s.charAt(0).toUpperCase())
+      .join('');
+    return `${num}${letter}${suffix}`;
+  }
+  return key
+    .split('_')
+    .filter(Boolean)
+    .map((s) => s.charAt(0).toUpperCase())
+    .join('') || key;
+}
+
+function deriveLong(key) {
+  return key
+    .split('_')
+    .map((w) => (w ? w[0].toUpperCase() + w.slice(1) : w))
+    .join(' ');
+}
+
+export function labelForKey(key) {
+  if (KNOWN[key]) return KNOWN[key];
+  const short = deriveShort(key);
+  return { short, long: deriveLong(key), icon: '⏱', usageLabel: short };
+}