claude-token-saver 2.0.2 → 2.1.0

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

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