claude-token-saver 3.28.3 → 3.30.0

package/README.en.md

@@ -173,6 +173,7 @@ Run these in your shell (inside Claude Code, the `/claude-token-saver` Skill is
 | `claude-token-saver update-check` | Is a newer version out? (`--refresh` to ask now, `--dismiss` to mute this version's offer) |
 | `claude-token-saver upgrade` | Install the latest release with the package manager that installed this copy (`--print` shows the command only) |
 | `claude-token-saver install` | Manually register Skill + statusline |
+| `claude-token-saver uninstall [--purge]` | Remove the hooks, statusline and skill it registered. Recorded savings are kept unless `--purge` is given |
 
 Switch output language with `mode ko` / `mode en` (English default; statusline chips stay symbolic).
 
@@ -451,7 +452,16 @@ Planning documents are moving from PowerPoint to Figma, so the same hook catches
 
 The result is an outline: pages and frames become headings, text nodes become body lines, and shapes are counted rather than listed — in a planning document the words are the content, and two hundred `Rectangle 173` lines would drown them. A file with no text at all is refused rather than dressed up as an empty document.
 
-Verified against real files: a community Bootstrap UI kit (8.1MB, 4,155 nodes, 1,312 of them text) and a 52MB Tailwind kit, each converting in under a second. Both `.fig` vintages parse — the current zip container and the older bare fig-kiwi stream. No savings are claimed: a `.fig` unzips to another binary, so there is no readable fallback to price against.
+Verified against real files: a community Bootstrap UI kit (8.1MB, 4,155 nodes, 1,312 of them text) and a 52MB Tailwind kit, each converting in under a second. Both `.fig` vintages parse — the current zip container and the older bare fig-kiwi stream.
+
+**`.fig` saves the most of any format.** Unlike the Office containers, `Read` does not refuse a `.fig`: the extension means nothing to it, so it pulls the binary in as text and the context window fills with tokenised noise. Measured against the same 42,760-token control:
+
+| File | Size | Extra tokens for a Read | Conversion |
+|---|---|---|---|
+| plan.fig | 26KB | +44,195 | 100 tokens |
+| bootstrap-kit.fig | 8.1MB | +43,994 | 18,397 tokens |
+
+Two files three hundred times apart in size cost the same, because Read truncates long before the file ends — you pay for a whole document and receive a fraction of one. The baseline is therefore a flat 44,000 tokens. For comparison, the same probe on a pptx cost +317 tokens and on a docx +185: a refusal message, and nothing else.
 
 ### Editing a document: copy, then script
 

package/README.md

@@ -172,6 +172,7 @@ Claude Code 안에서 `/claude-token-saver` Skill을 실행하거나, 칩에 적
 | `claude-token-saver update-check` | 새 버전이 있는지 확인합니다 (`--refresh`로 즉시 조회, `--dismiss`로 그 버전 안내 끄기) |
 | `claude-token-saver upgrade` | 설치 경로에 맞는 명령으로 최신 버전을 설치합니다 (`--print`로 실행 없이 명령만 확인) |
 | `claude-token-saver install` | Skill·statusline 수동 등록 |
+| `claude-token-saver uninstall [--purge]` | 등록한 훅·statusline·Skill 제거. 기록된 절감액은 남기며, `--purge` 를 붙이면 상태 디렉터리까지 지웁니다 |
 
 출력 언어는 `mode ko`와 `mode en`으로 전환합니다. 기본값은 영어이며, statusline의 칩은 언제나 기호로 표시합니다. 전체 옵션은 [영문 README](./README.en.md#options)를 참고하십시오.
 
@@ -447,7 +448,16 @@ PDF 는 첨부하면 모델이 내용을 그대로 읽습니다. 대신 페이
 
 변환 결과는 페이지·프레임 계층을 헤딩으로, 텍스트 노드를 본문으로 정리한 아웃라인입니다. 도형·벡터 같은 시각 요소는 나열하지 않고 개수만 남깁니다. 기획서에서 내용은 글이고, `Rectangle 173` 이 이백 줄 나오면 글이 묻히기 때문입니다. 텍스트가 하나도 없는 파일(순수 그래픽)은 빈 문서로 꾸미지 않고 변환 불가로 알립니다.
 
-실제 파일로 검증했습니다: 피그마 커뮤니티의 Bootstrap UI kit(8.1MB, 노드 4,155개, 텍스트 1,312개)와 Tailwind kit(52MB)이 각각 0.2초 안에 71.9KB·44KB 아웃라인으로 변환됐고, 한국어 텍스트 왕복도 무손실이었습니다. `.fig` 는 두 세대가 있습니다. 요즘 익스포트는 zip 컨테이너, 옛 익스포트는 fig-kiwi 바이너리 원형인데 둘 다 처리합니다. 절감액은 청구하지 않습니다. `.fig` 는 압축을 풀어도 또 바이너리라 비교할 대안 자체가 없고, 변환이 유일한 읽기 경로입니다.
+실제 파일로 검증했습니다: 피그마 커뮤니티의 Bootstrap UI kit(8.1MB, 노드 4,155개, 텍스트 1,312개)와 Tailwind kit(52MB)이 각각 0.2초 안에 71.9KB·44KB 아웃라인으로 변환됐고, 한국어 텍스트 왕복도 무손실이었습니다. `.fig` 는 두 세대가 있습니다. 요즘 익스포트는 zip 컨테이너, 옛 익스포트는 fig-kiwi 바이너리 원형인데 둘 다 처리합니다.
+
+**`.fig` 의 절감이 가장 큽니다.** 오피스 형식과 달리 `Read` 가 `.fig` 를 거부하지 않습니다. 확장자를 모르니 이진 파일을 그대로 텍스트로 읽어들이고, 컨텍스트가 토큰화된 잡음으로 찹니다. 같은 42,760 토큰 대조군으로 측정했습니다.
+
+| 파일 | 크기 | Read 가 더 쓴 토큰 | 변환본 |
+|---|---|---|---|
+| plan.fig | 26KB | +44,195 | 100 토큰 |
+| bootstrap-kit.fig | 8.1MB | +43,994 | 18,397 토큰 |
+
+크기가 300배 차이인데 비용이 같습니다. Read 가 상한에서 자르기 때문인데, 바꿔 말하면 **문서 전체 값을 치르고 일부만 받습니다.** 그래서 기준선은 파일 크기와 무관한 44,000 토큰 고정입니다. 참고로 같은 방법으로 재보니 pptx 는 +317, docx 는 +185 토큰이었습니다. 거부 메시지 한 줄이 전부입니다. 절감액은 청구하지 않습니다. `.fig` 는 압축을 풀어도 또 바이너리라 비교할 대안 자체가 없고, 변환이 유일한 읽기 경로입니다.
 
 ### 문서를 수정해야 할 때: 복사본 + 스크립트
 

package/bin/cli.js

@@ -141,6 +141,13 @@ async function main() {
     return (await import('../src/commands/install.js')).run({ hasFlag });
   }
 
+  // The counterpart to `install`. It was in the known-subcommand list from the
+  // start but had no dispatch, so it fell through to the usage report and
+  // exited non-zero — an unhelpful answer to "remove this".
+  if (args[0] === 'uninstall') {
+    return (await import('../src/commands/uninstall.js')).run({ hasFlag, args });
+  }
+
   // Subcommand: mode — persist statusline preferences so future runs pick
   // them up without flags or wrapper edits.
   //   claude-token-saver mode                    # show current config
@@ -395,6 +402,18 @@ async function main() {
       ));
       return;
     }
+    // JSON mode stays JSON. A caller that asked for machine-readable output
+    // and got a paragraph of advice has to parse prose to find out nothing
+    // was found, which is exactly the failure this format exists to avoid.
+    if (getArg('--format') === 'json') {
+      console.log(JSON.stringify({
+        sessions: 0,
+        days,
+        error: 'no-session-data',
+        message: 'No Claude Code session logs found for the given period.',
+      }, null, 2));
+      process.exit(1);
+    }
     console.log('No session data found for the given period.');
     console.log('');
     console.log('This tool analyzes Claude Code session logs (~/.claude/projects/).');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-token-saver",
-  "version": "3.28.3",
+  "version": "3.30.0",
   "description": "Route the easy work your expensive Claude model keeps repeating down to haiku/sonnet — post-hoc session analysis, no realtime router, no extra LLM calls.",
   "type": "module",
   "bin": {

package/src/commands/harness.js

@@ -268,7 +268,7 @@ export async function run({ args, hasFlag }) {
         try {
           const { spawn } = await import('node:child_process');
           spawn(process.execPath, [process.argv[1], 'route-scan', '--refresh', '--quiet'],
-            { detached: true, stdio: 'ignore' }).unref();
+            { detached: true, stdio: 'ignore', windowsHide: true }).unref();
         } catch (e) { debug('promote:spawn-refresh', e); /* baseline arrives on the next gated rescan */ }
         return;
       }

package/src/commands/route-scan.js

@@ -205,7 +205,7 @@ export async function run({ args, hasFlag, numArg }) {
         try {
           const { spawn } = await import('node:child_process');
           spawn(process.execPath, [process.argv[1], 'route-scan', '--refresh', '--quiet'],
-            { detached: true, stdio: 'ignore' }).unref();
+            { detached: true, stdio: 'ignore', windowsHide: true }).unref();
         } catch (e) { debug('route-scan:spawn-refresh', e); /* stale cache is still usable below */ }
       }
       const open = rs.openCandidates(cache);

package/src/commands/uninstall.js

@@ -0,0 +1,42 @@
+/**
+ * Subcommand: uninstall — take the integration back out of ~/.claude.
+ *
+ *   claude-token-saver uninstall           # hooks, statusline, skill
+ *   claude-token-saver uninstall --purge   # the above plus recorded state
+ *
+ * Recorded savings are kept by default. Someone removing an integration is
+ * usually not asking to throw away the ledger that says what it saved, and
+ * that data cannot be reconstructed once the transcripts age out.
+ */
+
+export async function run({ hasFlag, args = [] }) {
+  const { uninstallAll } = await import('../installer.js');
+  const { userLanguage } = await import('../config.js');
+  const lang = userLanguage();
+  const purge = hasFlag('--purge') || args.includes('--purge');
+
+  const r = uninstallAll({ purge });
+
+  if (r.action === 'skipped') {
+    console.error(lang === 'ko'
+      ? `✗ ${r.path} 를 읽지 못해 아무것도 지우지 않았습니다: ${r.reason}`
+      : `✗ nothing removed — ${r.path} could not be read: ${r.reason}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  if (r.removed.length === 0) {
+    console.log(lang === 'ko' ? '설치된 항목이 없습니다.' : 'Nothing was installed.');
+  } else {
+    console.log(lang === 'ko' ? `✓ 제거했습니다 (${r.path}):` : `✓ removed (${r.path}):`);
+    for (const item of r.removed) console.log(`  - ${item}`);
+  }
+  for (const item of r.kept) {
+    console.log(lang === 'ko' ? `  유지: ${item}` : `  kept: ${item}`);
+  }
+  if (!purge) {
+    console.log(lang === 'ko'
+      ? '  기록된 절감액과 설정까지 지우려면 `claude-token-saver uninstall --purge` 를 실행하십시오.'
+      : '  To remove recorded savings and settings too: `claude-token-saver uninstall --purge`.');
+  }
+}

package/src/doc2md-ledger.cjs

@@ -31,9 +31,11 @@
  *
  * pptx/xlsx/docx: unpacking the container. These never reach the model as
  * attachments at all — the same probe on a docx added 78 tokens and the model
- * replied that it had no file, and Read refuses the format outright. What a
- * reader does instead is unzip the archive and wade through its XML, where
- * tags and style attributes outweigh the text many times over:
+ * replied that it had no file. Read refuses them too, measured the same way:
+ * a Read of the 31.8MB deck cost +317 tokens and of the 185KB docx +185, which
+ * is a refusal message and nothing more. What a reader does instead is unzip
+ * the archive and wade through its XML, where tags and style attributes
+ * outweigh the text many times over:
  *
  *   aws-summit-seoul.pptx   2.1MB of slide XML   ~540,429 tokens   23.8× the conversion
  *   우리은행이력서.docx      312KB of body XML    ~78,113 tokens    ~46× the conversion
@@ -43,6 +45,21 @@
  * a real fallback — this very session unzipped a pptx to verify a conversion
  * before this ledger existed.
  *
+ * .fig: the file itself. Unlike the Office formats, Read does not refuse a
+ * .fig — the extension means nothing to it, so it pulls the binary in as text
+ * and the context window fills with tokenised noise. Measured against the same
+ * 42,760-token control:
+ *
+ *   plan.fig            26KB    +44,195 tokens   conversion: 100
+ *   bootstrap-kit.fig   8.1MB   +43,994 tokens   conversion: 18,397
+ *
+ * Two files three hundred times apart in size cost the same, because Read
+ * truncates at a cap long before the file ends — which also means the reader
+ * gets a fraction of a document for the price of a whole one. The baseline is
+ * therefore a flat 44,000 tokens rather than anything per-byte. An earlier
+ * version of this file claimed .fig had no measurable baseline at all; that
+ * was an assumption about Read's behaviour that turned out to be wrong.
+ *
  * Erring low is deliberate throughout. A savings figure that flatters the
  * tool is worth less than one the user can trust.
  *
@@ -79,10 +96,10 @@ const ATTACHMENT_BASELINE = {
   '.docx': { markup: true },
   '.xlsx': { markup: true },
   '.xls': { ratio: 1 },
-  // A .fig unzips to another binary (Figma's kiwi format), so unlike the
-  // office containers there is no readable markup to price the fallback
-  // against. Converting is the only way to read it at all; no money claimed.
-  '.fig': { ratio: 1 },
+  // Read swallows a .fig instead of refusing it, at a flat ~44,000 tokens
+  // whatever the file's size (see the header). Rounded down from the two
+  // measurements, both of which landed just under 44,200.
+  '.fig': { fixed: 44_000 },
 };
 
 /**
@@ -106,7 +123,9 @@ function estimateSaving({ ext, pages = 0, markupBytes = 0, markdown = '' }) {
   const tokens = estimateTokens(markdown);
   const rule = ATTACHMENT_BASELINE[String(ext).toLowerCase()] || { ratio: 1 };
   let baseline;
-  if (rule.perPage && pages > 0) {
+  if (rule.fixed) {
+    baseline = rule.fixed;
+  } else if (rule.perPage && pages > 0) {
     baseline = pages * rule.perPage;
   } else if (rule.markup && markupBytes > 0) {
     baseline = Math.ceil(markupBytes / 4);

package/src/doc2md.cjs

@@ -165,10 +165,13 @@ function banner(sourcePath, saving) {
   if (saving.usd > 0) {
     const savedTokens = Math.max(0, saving.baseline - saving.tokens);
     // The alternative differs by format, so the sentence names it: a PDF
-    // would have been attached, a zip document would have been unpacked.
-    const alternative = path.extname(sourcePath).toLowerCase() === '.pdf'
-      ? '원본을 첨부하면'
-      : '압축을 풀어 본문 XML을 읽으면';
+    // would have been attached, a zip document unpacked, and a .fig read
+    // straight into the context window, which is the one Read does not
+    // refuse.
+    const ext = path.extname(sourcePath).toLowerCase();
+    const alternative = ext === '.pdf' ? '원본을 첨부하면'
+      : ext === '.fig' ? '원본을 그대로 Read 하면'
+        : '압축을 풀어 본문 XML을 읽으면';
     lines.push(
       `${alternative} 약 ${saving.baseline.toLocaleString('en-US')} 토큰이 드는데, `
       + `변환본은 ${saving.tokens.toLocaleString('en-US')} 토큰입니다. `

package/src/formatters/statusline.js

@@ -423,9 +423,19 @@ export function formatReport(data, { color = true, verbose = false, timer = true
   if (!singleLine && doc2mdUsd > 0) {
     const head = isIcon ? '📄 Doc2md saved' : 'Doc2md saved';
     const byExt = Array.isArray(doc2md.byExt) ? doc2md.byExt : [];
-    const extText = byExt
-      .map((r) => `${c(GRAY)}${r.ext} ${r.docs}× ${formatMoney(r.usd)}${c(RESET)}`)
-      .join(` ${c(GRAY)}·${c(RESET)} `);
+    // Formats that earned money show it; formats with no baseline to measure
+    // against are counted instead. Printing "$0.00" next to real amounts reads
+    // as "this format saved nothing", when what it means is that nobody has
+    // measured what the alternative costs. Only .xls sits there now — the
+    // pre-2007 binary, which has no container to price against.
+    const paid = byExt.filter((r) => r.usd > 0);
+    const unpriced = byExt.filter((r) => !(r.usd > 0));
+    const parts = paid.map((r) => `${c(GRAY)}${r.ext} ${r.docs}× ${formatMoney(r.usd)}${c(RESET)}`);
+    if (unpriced.length) {
+      const counted = unpriced.map((r) => `${r.ext} ${r.docs}×`).join(' · ');
+      parts.push(`${c(GRAY)}${counted} ${verbose ? '(no baseline)' : '(n/a)'}${c(RESET)}`);
+    }
+    const extText = parts.join(` ${c(GRAY)}·${c(RESET)} `);
     doc2mdLine =
       `${c(GREEN)}${c(BOLD)}${head}${c(RESET)} ` +
       `${c(GREEN)}${formatMoney(doc2mdUsd)}${c(RESET)}` +

package/src/harness.js

@@ -11,6 +11,7 @@ import { readFileSync, writeFileSync, existsSync, mkdirSync, statSync } from 'no
 import { join, resolve, dirname } from 'node:path';
 import { homedir } from 'node:os';
 import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
 import {
   HARNESS_SECTIONS,
   HARNESS_BLOCK_BEGIN,
@@ -368,7 +369,10 @@ export function harnessPull({ root = findProjectRoot(), scope = 'global' } = {})
 /** Parse the bundled preset rules (markdown bullets under presets/). */
 export function presetRules() {
   try {
-    const path = join(dirname(new URL(import.meta.url).pathname), '..', 'presets', 'ratchet-rules.md');
+    // fileURLToPath, not `.pathname`: the latter yields `/D:/repo/src` on
+    // Windows, where the read fails and the catch below turns a missing
+    // file into an empty rule set without ever saying so.
+    const path = join(dirname(fileURLToPath(import.meta.url)), '..', 'presets', 'ratchet-rules.md');
     return readFileSync(path, 'utf8')
       .split('\n')
       .filter((l) => /^\s*-\s+/.test(l))

package/src/installer.js

@@ -13,9 +13,9 @@
  * exist on every platform.
  */
 
-import { writeFileSync, mkdirSync, existsSync, unlinkSync, readFileSync } from 'node:fs';
+import { writeFileSync, mkdirSync, existsSync, unlinkSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
-import { claudeUserDir } from './paths.js';
+import { claudeUserDir, userDataDir } from './paths.js';
 
 const STATUSLINE_COMMAND = 'claude-token-saver --statusline --icon';
 const STATUSLINE_REFRESH_INTERVAL = 5;
@@ -469,6 +469,85 @@ export function removeDoc2mdHook() {
   return { path: file, action: 'removed' };
 }
 
+/**
+ * Undo what `install` did: every hook this tool registered, the statusline
+ * entry when it is still ours, and the skill file.
+ *
+ * Written because `uninstall` was a name in the subcommand list with no
+ * implementation behind it — running it fell through to the usage report and
+ * exited non-zero, which is a poor answer to "get this off my machine". A
+ * company rollout needs the way out to work as well as the way in.
+ *
+ * User data (ledgers, config, conversion cache) is deliberately left alone:
+ * removing an integration should not throw away months of recorded savings.
+ * `--purge` is the separate, explicit request for that.
+ */
+export function uninstallAll({ purge = false } = {}) {
+  const file = join(claudeUserDir(), 'settings.json');
+  const result = { removed: [], kept: [], path: file };
+
+  if (existsSync(file)) {
+    let settings;
+    try {
+      settings = JSON.parse(readFileSync(file, 'utf8'));
+    } catch (e) {
+      return { ...result, action: 'skipped', reason: `unreadable JSON (${e.message})` };
+    }
+
+    // Only our own statusline command goes. Someone else's stays exactly
+    // where they put it.
+    const cur = settings.statusLine;
+    if (cur && typeof cur.command === 'string' && cur.command.includes('claude-token-saver')) {
+      delete settings.statusLine;
+      result.removed.push('statusLine');
+    } else if (cur) {
+      result.kept.push(`statusLine (${cur.command || 'unrecognised'})`);
+    }
+
+    // Every event, every entry whose command is this CLI. Matching on the
+    // binary name rather than a list of exact commands means a hook added by
+    // an older version is still removed by a newer one.
+    for (const event of Object.keys(settings.hooks || {})) {
+      const list = settings.hooks[event];
+      if (!Array.isArray(list)) continue;
+      const kept = list.filter((m) => !(
+        Array.isArray(m?.hooks)
+        && m.hooks.some((h) => typeof h?.command === 'string' && h.command.includes('claude-token-saver'))
+      ));
+      if (kept.length === list.length) continue;
+      result.removed.push(`hooks.${event}`);
+      if (kept.length === 0) delete settings.hooks[event];
+      else settings.hooks[event] = kept;
+    }
+    if (settings.hooks && Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+    writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  }
+
+  const skillDir = join(claudeUserDir(), 'skills', 'claude-token-saver');
+  if (existsSync(skillDir)) {
+    rmSync(skillDir, { recursive: true, force: true });
+    result.removed.push('skill');
+  }
+  const legacyCommand = join(claudeUserDir(), 'commands', 'token-monitor.md');
+  if (existsSync(legacyCommand)) {
+    rmSync(legacyCommand, { force: true });
+    result.removed.push('legacy command');
+  }
+
+  if (purge) {
+    const data = userDataDir();
+    if (existsSync(data)) {
+      rmSync(data, { recursive: true, force: true });
+      result.removed.push('state directory');
+    }
+  } else {
+    result.kept.push('state directory (savings ledgers, config, cache) — remove with --purge');
+  }
+
+  return { ...result, action: 'removed' };
+}
+
 export function installAll({ force = false } = {}) {
   return {
     skill: installSkill({ force }),

package/src/update-check.js

@@ -119,6 +119,9 @@ export function maybeSpawnUpdateCheck(currentVersion) {
     spawn(process.execPath, [cliEntryPath(), 'update-check', '--refresh', '--quiet'], {
       detached: true,
       stdio: 'ignore',
+      // Without this Windows flashes a console window, and this one
+      // re-spawns from the statusline — several times a minute.
+      windowsHide: true,
     }).unref();
     return true;
   } catch (e) {