claude-token-saver 2.5.0 → 2.6.0

package/README.md

@@ -12,7 +12,7 @@
 **Why I built this.** I'm on the Max plan. On Opus 4.6 I never hit the *current-session* cap. After Opus 4.7 rolled out, I started hitting it on the same workflow — repeatedly. The official token statistics didn't match what I was actually feeling, and Claude Code's UI doesn't show prompt-cache health. This tool is what let me see *why*: low cache hit rate, 5m TTL writes that should have been 1h, 1M context auto-promoted in the background.
 
 v2.1 (2026-04) adds the workflow that follows the diagnosis:
-- **`claude-token-saver install`** — one command writes a Claude Code Skill (auto-activates when you mention "cache hit rate" / "1M context" / etc.) and a `/token-monitor` slash command.
+- **`claude-token-saver install`** — one command writes a Claude Code Skill that auto-activates when you mention "cache hit rate" / "1M context" / "5H cap" — no slash command needed.
 - **`claude-token-saver history`** — every warning chip transition is auto-logged to a daily Markdown file, so you can answer "when did this start" without grepping logs.
 - **Cross-platform paths** — Windows (`%APPDATA%`), macOS (`~/Library/Application Support`), Linux (`~/.config` / XDG) all handled.
 
@@ -208,11 +208,12 @@ One command wires up everything else this README mentions:
 claude-token-saver install
 ```
 
-This writes two files under your Claude user dir:
-- `~/.claude/skills/claude-token-saver/SKILL.md` — auto-activates whenever you mention chip wording ("⚠ 1M ON", "cache miss", etc.) or ask about token usage. Claude Code will then know to read history, drill into the table report, and explain the warning.
-- `~/.claude/commands/token-monitor.md` — adds a `/token-monitor` slash command that runs `claude-token-saver history` + a fresh report and summarizes both for you.
+This writes one file under your Claude user dir:
+- `~/.claude/skills/claude-token-saver/SKILL.md` — auto-activates whenever you mention chip wording ("⚠ 1M ON", "cache miss", "5H cap", etc.) or ask for a token report. Claude Code will then read `claude-token-saver last`, drill into history if needed, and explain the warning.
 
-Re-run with `--force` to overwrite. Install only one piece with `install --skill` or `install --command`.
+If you previously installed v2.5.x or earlier, `install` also removes the now-redundant legacy `~/.claude/commands/token-monitor.md` slash command — its workflow is fully absorbed into the skill (same behavior, triggered by intent rather than typing `/token-monitor`).
+
+Re-run with `--force` to overwrite the skill file.
 
 ## Warning history (`history`) — new in v2.1
 
@@ -286,7 +287,7 @@ That writes `./HANDOFF-YYYY-MM-DD-HHMM.md` in the current directory with:
   Read the most recent HANDOFF-*.md in this directory and continue the work.
   ```
 
-The handoff write is also recorded in history (`📝 handoff written: …`), so `/token-monitor` and `claude-token-saver history` show both the cap-warn and the backup event next to each other.
+The handoff write is also recorded in history (`📝 handoff written: …`), so `claude-token-saver history` and the auto-skill show both the cap-warn and the backup event next to each other.
 
 ## Hook Setup
 

package/bin/cli.js

@@ -201,9 +201,9 @@ function findLatestWarning(historyEntries, chipToCodes) {
 
 async function main() {
   // Subcommand: last — print the most recent warning + how to handle it.
-  // Designed for the /token-monitor slash command and the auto-skill so the
-  // user immediately sees "what just fired and how to fix it" without having
-  // to read the whole history file.
+  // Designed for the auto-trigger skill so the user immediately sees
+  // "what just fired and how to fix it" without having to read the whole
+  // history file.
   //   claude-token-saver last           # search last 1 day
   //   claude-token-saver last --days 7  # widen the lookback
   if (args[0] === 'last') {
@@ -329,38 +329,31 @@ async function main() {
     return;
   }
 
-  // Subcommand: install — write the Claude Code Skill and slash command so
-  // /token-monitor and the auto-trigger skill become available without any
-  // manual file editing. Cross-platform (uses node:path + node:fs).
-  //   claude-token-saver install              # install both
-  //   claude-token-saver install --skill      # only the skill
-  //   claude-token-saver install --command    # only the slash command
-  //   claude-token-saver install --force      # overwrite existing files
+  // Subcommand: install — write the Claude Code auto-trigger skill so the
+  // user can just mention chip wording and Claude responds. v2.6.0 dropped
+  // the redundant /token-monitor slash command in favor of the skill alone;
+  // a legacy command file is removed automatically. Cross-platform.
+  //   claude-token-saver install              # install/update the skill
+  //   claude-token-saver install --force      # overwrite existing skill file
   if (args[0] === 'install') {
-    const { installSkill, installCommand, installAll } = await import('../src/installer.js');
+    const { installAll } = await import('../src/installer.js');
     const force = hasFlag('--force');
-    const onlySkill = hasFlag('--skill');
-    const onlyCommand = hasFlag('--command');
     const print = (kind, r) => {
       const verb = r.action === 'exists' ? 'already exists' : r.action;
       console.log(`  ${kind}: ${r.path} (${verb})`);
     };
-    if (onlySkill && !onlyCommand) {
-      print('skill', installSkill({ force }));
-    } else if (onlyCommand && !onlySkill) {
-      print('command', installCommand({ force }));
-    } else {
-      const r = installAll({ force });
-      print('skill', r.skill);
-      print('command', r.command);
+    const r = installAll({ force });
+    print('skill', r.skill);
+    if (r.legacy.action === 'removed') {
+      print('legacy /token-monitor', r.legacy);
+      console.log('  (consolidated into the skill — same workflow, triggered by intent)');
     }
     console.log('');
-    console.log('Open Claude Code in any directory and try:');
-    console.log('  /token-monitor');
-    console.log('Or just mention "cache hit rate" / "1M context" — the skill auto-activates.');
+    console.log('Open Claude Code in any directory and just mention:');
+    console.log('  "cache hit rate" / "1M context" / "5H cap" — the skill auto-activates.');
     if (!force) {
       console.log('');
-      console.log('Tip: re-run with --force to overwrite existing files.');
+      console.log('Tip: re-run with --force to overwrite the existing skill file.');
     }
     return;
   }
@@ -562,8 +555,8 @@ async function main() {
   // refresh. Pull rate_limits + model out of it so we can surface cap-warn
   // (>=90%) chips, always-on usage segments, the model chip, record cap
   // transitions, and seed the table view's warning box. The table path falls
-  // back to the most-recent cached snapshot so the /token-monitor slash
-  // command (which doesn't pipe stdin) still has the data.
+  // back to the most-recent cached snapshot so the table view (which
+  // doesn't pipe stdin) still has the data.
   const stdinJson = readStdinJson();
   let caps = extractCaps(stdinJson);
   let model = extractModel(stdinJson);
@@ -616,7 +609,7 @@ async function main() {
       }
     }
     // Persist transitions to ~/.config/claude-token-saver/history/YYYY-MM-DD.md
-    // so /token-monitor and `claude-token-saver history` can replay them.
+    // so `claude-token-saver history` and the auto-skill can replay them.
     try {
       const { recordChip, recordCapTransition } = await import('../src/history.js');
       recordChip(spikeChip, { detail: chipDetail });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Save tokens on Claude Code — spike diagnosis, 1M-context detection, TTL countdown, statusline. (formerly claude-cache-monitor)",
   "type": "module",
   "bin": {

package/src/caps-cache.js

@@ -1,7 +1,7 @@
 /**
  * Statusline snapshot cache — the rate-limit numbers and model name 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 data. So
+ * view (`claude-token-saver --days N`) to surface the same data. So
  * whenever the statusline path sees them it writes them here, and the table
  * path reads them back if its own stdin was empty.
  *

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,6 +40,9 @@ 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
 
@@ -97,41 +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 — most
-importantly: **what just happened, and how do I handle it?**
-
-Steps:
-
-1. **Lead with the most recent warning.** Run \`claude-token-saver last\`
-   first and surface its output verbatim (or lightly summarized) at the top
-   of your reply. This returns the latest warning event (chip + detail +
-   timestamp) followed by the full advice block. If \`last\` says no recent
-   warnings, mention that and skip ahead — you can stop here unless the user
-   asked for more.
-2. Run \`claude-token-saver history --days 7\` and capture the output. Use it
-   only to add context — e.g. "this is the 3rd cache miss today" — not to
-   re-print the whole file. Each entry is bilingual and includes a \`💡\`
-   action tip inline.
-3. Run \`claude-token-saver --days 1\` and capture the output for any extra
-   color you want to add: TTL breakdown, cost impact, daily trend, or active
-   spikes. Skip if step 1 already covered what the user needs.
-4. Summarize for the user:
-   - **What just fired** — the chip + the time + a sentence on what caused it
-     (from \`last\`).
-   - **What to do** — the action tip from \`last\`. For cap-warn (\`🚨 5H/7D NN%\`),
-     surface \`claude-token-saver handoff\` prominently so they can back up
-     state before the cap blocks them.
-   - **Today's pattern** (optional) — when warnings cluster in time, mention it.
-
-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' };
@@ -146,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(),
   };
 }