claude-slim 2.8.0 → 2.9.0

package/README.md

@@ -3,7 +3,9 @@
 # claude-slim
 
 [![npm](https://img.shields.io/npm/v/claude-slim.svg)](https://www.npmjs.com/package/claude-slim)
+[![downloads](https://img.shields.io/npm/dm/claude-slim.svg)](https://www.npmjs.com/package/claude-slim)
 [![CI](https://github.com/iops-leo/claude-slim/actions/workflows/ci.yml/badge.svg)](https://github.com/iops-leo/claude-slim/actions/workflows/ci.yml)
+[![node](https://img.shields.io/node/v/claude-slim.svg)](https://nodejs.org)
 [![license](https://img.shields.io/npm/l/claude-slim.svg)](./LICENSE)
 
 **Your Claude Code session burns thousands of tokens before you even say "hello."**
@@ -28,17 +30,20 @@ No proxy, no compression, no changes to how Claude Code talks to the API — it
   <img src="docs/demo.gif" alt="claude-slim cleanup: 11,442 tokens of overhead reduced to ~5,800 in 45 seconds" width="900" />
 </p>
 
-Where the bloat hides:
+Where the bloat hides — measured on one real install:
 
-| Source | Typical overhead |
-|--------|:---:|
-| 60+ registered skills | ~3,000 tokens |
-| CLAUDE.md (plugin instructions) | ~5,000 tokens |
-| Memory files | ~2,500 tokens |
-| Deferred tools list | ~1,500 tokens |
-| **Total** | **~12,000 tokens** |
+| Source | What it costs | |
+|--------|:---:|---|
+| Skill listings | ~10,100 tokens | 256 skills × their `name: description` line |
+| Agent catalog | ~2,250 tokens | `~/.claude/agents/`, 12 agents |
+| CLAUDE.md | ~2,000 tokens | plugin instructions |
+| Deferred tools list | ~1,500 tokens | MCP tool schemas |
+| Slash commands | ~80 tokens | `~/.claude/commands/` |
+| Memory files | **0 – 63,500 tokens** | current project only — varies wildly per project |
 
-That's slower responses. Hitting your usage cap faster. Paying for context you're not using.
+Skill listings are the part people underestimate: each installed skill contributes one `- name: description` line to the system prompt, and those run anywhere from **30 to 509 tokens each**. Sixty terse skills and sixty verbose ones are not the same bill.
+
+That's slower responses. Hitting your usage cap faster. Paying for context you're not using — on every turn, of every session.
 
 ---
 
@@ -144,6 +149,7 @@ Then just type `/claude-slim` in any session.
 /claude-slim scan --json              # Machine-readable JSON output
 /claude-slim scan --lookback-days 30  # Treat skills idle for 30+ days as unused
 /claude-slim doctor                   # Check scanner prerequisites and data fidelity
+/claude-slim check-update             # Is a newer version published?
 /claude-slim restore                  # Bring back anything you disabled
 ```
 
@@ -156,10 +162,26 @@ npx claude-slim clean --auto             # Non-interactive, Tier 1 only (CI/scri
 npx claude-slim clean --lookback-days N  # Tune the unused-skill detection window
 npx claude-slim scan                     # Report only
 npx claude-slim doctor                   # Diagnose Node/Claude/session-log readiness
+npx claude-slim doctor --offline         # Same, without the version check (no network)
+npx claude-slim check-update             # Report-only version check
 npx claude-slim restore                  # Undo
 npx claude-slim report                   # Show savings from last clean
 ```
 
+### Staying current
+
+An outdated claude-slim doesn't just miss features — it reports **wrong numbers**. Versions before 2.8.0 inflated the startup estimate roughly 8×, and nothing told you that you were behind.
+
+`doctor` now compares your installed version against npm and prints the upgrade command for how you actually installed it:
+
+```
+! Version: 2.0.0 installed, 2.8.1 available
+    Outdated versions report wrong token totals. Update with:
+    claude plugin marketplace update claude-slim && claude plugin update claude-slim@claude-slim
+```
+
+claude-slim never updates itself — that's your package manager's job, and writing into a directory `claude plugin` owns is how installs get corrupted. It only tells you. The check is the tool's only outbound request, is skipped with `--offline`, caches for 24h, and fails open when you're offline.
+
 ---
 
 ## Safety first
@@ -176,6 +198,7 @@ npx claude-slim report                   # Show savings from last clean
 
 - **`~/.claude/CLAUDE.md`** — your system instructions, read-only.
 - **`~/.claude/settings.json`** — MCP server config, hooks, and any other settings. Read-only.
+- **`~/.claude/agents/` and `~/.claude/commands/`** — measured and reported since v2.8, never moved or deleted. There is no restore path for them yet, and a destructive action without its undo isn't worth shipping.
 - **Plugin internals** (`~/.claude/plugins/config.json`, individual `plugin.json` files) — left alone; use `claude plugin` to manage plugins.
 - **Git / project sources** — claude-slim only looks inside `~/.claude/`, never at your code.
 - **Anything outside `~/.claude/`** — a path-containment guard refuses destructive ops anywhere else, even if a tampered manifest asked it to.
@@ -214,6 +237,12 @@ From a real cleanup session:
 | Memory files | 15KB | 2KB | **-87%** |
 | **Est. token savings** | | **~4,300/session** | |
 
+### A note on the numbers
+
+claude-slim reports what a session in **this** directory pays. Memory is per-project — Claude Code loads `~/.claude/projects/<slug>/memory/` for the project you're in, not every project on disk — so running `scan` from two different repos will legitimately give you two different totals.
+
+Token counts come from [js-tiktoken](https://github.com/nicolo-ribaudo/js-tiktoken) against the actual file contents. The only estimates left are marked with `~`: MCP tool schemas (~8 tokens/tool) and skills whose frontmatter can't be parsed (~30 tokens). Everything else is measured.
+
 ---
 
 ## v2.8.0 — What's new

package/dist/cli.js

@@ -10,6 +10,7 @@ import { cleanIssues, restoreItem } from './cleaner.js';
 import { readManifest } from './manifest.js';
 import { formatScanSummary, formatReportBox, calculateReport, } from './report.js';
 import { collectDoctorReport, formatDoctorReport } from './doctor.js';
+import { checkForUpdate, formatUpdateNotice } from './update-check.js';
 import { resolveSelection, resolveRestoreSelection } from './selection.js';
 const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
 const { version: PKG_VERSION } = JSON.parse(readFileSync(pkgPath, 'utf-8'));
@@ -52,9 +53,11 @@ program
     .description('Check local Claude Code environment and scanner fidelity')
     .option('--json', 'Output raw JSON')
     .option('--lookback-days <n>', 'Days of session history for skill-usage analysis', '60')
+    .option('--offline', 'Skip the npm version check (no outbound request)')
     .action(async (opts) => {
     const report = await collectDoctorReport({
         lookbackDays: parseNonNegativeInt(opts.lookbackDays, 60),
+        checkUpdate: !opts.offline,
     });
     if (opts.json) {
         console.log(JSON.stringify(report, null, 2));
@@ -63,6 +66,31 @@ program
         console.log(formatDoctorReport(report));
     }
 });
+// --- check-update ---
+// Detection only. Updating is the package manager's job — claude-slim writing
+// into a directory `claude plugin` owns is how installs get corrupted.
+program
+    .command('check-update')
+    .description('Check whether a newer claude-slim is published (no changes made)')
+    .option('--json', 'Output raw JSON')
+    .option('--force', 'Ignore the 24h cache and re-query the registry')
+    .action(async (opts) => {
+    const result = await checkForUpdate({ force: Boolean(opts.force) });
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    const notice = formatUpdateNotice(result);
+    if (notice) {
+        console.log(`\n  \x1b[33m${notice}\x1b[0m\n`);
+    }
+    else if (result.latest === null) {
+        console.log(`\n  Could not reach the npm registry. Installed: ${result.installed}\n`);
+    }
+    else {
+        console.log(`\n  \x1b[32m✓\x1b[0m claude-slim ${result.installed} is up to date.\n`);
+    }
+});
 // --- clean ---
 program
     .command('clean')

package/dist/doctor.d.ts

@@ -1,3 +1,4 @@
+import { type UpdateCheckResult } from './update-check.js';
 export type DoctorStatus = 'ok' | 'warn' | 'fail';
 export interface DoctorCheck {
     label: string;
@@ -11,5 +12,6 @@ export interface DoctorReport {
 export declare function isSupportedRuntimeNode(version: string): boolean;
 export declare function collectDoctorReport(opts?: {
     lookbackDays?: number;
+    checkUpdate?: boolean | (() => Promise<UpdateCheckResult>);
 }): Promise<DoctorReport>;
 export declare function formatDoctorReport(report: DoctorReport): string;

package/dist/doctor.js

@@ -2,6 +2,7 @@ import { access, readdir } from 'node:fs/promises';
 import { getClaudeDir, getPluginsDir, getProjectsDir, getSkillsDir } from './paths.js';
 import { runCommand } from './scanner/fs-walk.js';
 import { scanSessionUsage } from './scanner/sessions.js';
+import { checkForUpdate } from './update-check.js';
 const MIN_RUNTIME_NODE_MAJOR = 20;
 export function isSupportedRuntimeNode(version) {
     const normalized = version.trim().replace(/^v/, '');
@@ -87,6 +88,37 @@ export async function collectDoctorReport(opts = {}) {
                 : 'Unused-skill detection will be suppressed until enough reliable session data exists.',
         });
     }
+    // Version drift, last: it is the only check that touches the network, and it
+    // is opt-in so `doctor` stays offline-safe when the caller wants that.
+    if (opts.checkUpdate) {
+        const run = typeof opts.checkUpdate === 'function' ? opts.checkUpdate : checkForUpdate;
+        const update = await run();
+        if (update.latest === null) {
+            checks.push({
+                label: 'Version',
+                status: 'warn',
+                detail: `${update.installed} installed, latest unknown`,
+                hint: 'Could not reach the npm registry. This does not affect scanning.',
+            });
+        }
+        else if (update.outdated) {
+            checks.push({
+                label: 'Version',
+                status: 'warn',
+                detail: `${update.installed} installed, ${update.latest} available`,
+                hint: update.upgradeCommand
+                    ? `Outdated versions report wrong token totals. Update with: ${update.upgradeCommand}`
+                    : 'Outdated versions report wrong token totals — update via your package manager.',
+            });
+        }
+        else {
+            checks.push({
+                label: 'Version',
+                status: 'ok',
+                detail: `${update.installed} (latest)`,
+            });
+        }
+    }
     return { checks };
 }
 export function formatDoctorReport(report) {

package/dist/tokenizer.js

@@ -11,13 +11,18 @@ function getCachePath() {
 let cache = { version: 1, entries: {} };
 let cacheDirty = false;
 export async function initTokenizer() {
-    try {
-        // cl100k_base is closest to Claude's tokenizer (gpt-4o uses o200k_base which undercounts by ~15%)
-        const { getEncoding } = await import('js-tiktoken');
-        encoder = getEncoding('cl100k_base');
-    }
-    catch {
-        useFallback = true;
+    // Building the cl100k_base encoder parses a large rank table — hundreds of
+    // milliseconds, and far more under CPU contention. It is immutable once
+    // built, so reuse it across calls. Only the cache is per-init state.
+    if (encoder === null && !useFallback) {
+        try {
+            // cl100k_base is closest to Claude's tokenizer (gpt-4o uses o200k_base which undercounts by ~15%)
+            const { getEncoding } = await import('js-tiktoken');
+            encoder = getEncoding('cl100k_base');
+        }
+        catch {
+            useFallback = true;
+        }
     }
     // Reset in-memory state so repeated initTokenizer() calls (e.g. across
     // test cases) don't bleed cache entries from a prior invocation.

package/dist/update-check.d.ts

@@ -0,0 +1,38 @@
+export type InstallMethod = 'plugin' | 'global' | 'npx' | 'source' | 'unknown';
+export interface UpdateCheckResult {
+    installed: string;
+    /** null when the lookup failed or was skipped — never treat as "up to date". */
+    latest: string | null;
+    outdated: boolean;
+    installMethod: InstallMethod;
+    /** The command that actually upgrades this install, or null if unknown. */
+    upgradeCommand: string | null;
+    fromCache: boolean;
+}
+/**
+ * Compare dotted numeric versions. Returns >0 if a is newer, <0 if b is newer.
+ * Pre-release suffixes (`-beta.1`) sort below the same release, matching semver
+ * closely enough for "is there something newer" without pulling in a dep.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Infer how this copy was installed from where it sits on disk, so the hint we
+ * print is the command that will actually work for this user.
+ */
+export declare function detectInstallMethod(modulePath: string): InstallMethod;
+export declare function upgradeCommandFor(method: InstallMethod): string | null;
+export declare function getInstalledVersion(): string;
+export interface CheckOptions {
+    installed?: string;
+    modulePath?: string;
+    cachePath?: string;
+    now?: number;
+    ttlMs?: number;
+    /** Ignore a fresh cache entry and re-query. */
+    force?: boolean;
+    /** Injected for tests; defaults to the real registry lookup. */
+    fetchLatest?: () => Promise<string | null>;
+}
+export declare function checkForUpdate(opts?: CheckOptions): Promise<UpdateCheckResult>;
+/** One-line human summary; null when there is nothing worth saying. */
+export declare function formatUpdateNotice(result: UpdateCheckResult): string | null;

package/dist/update-check.js

@@ -0,0 +1,177 @@
+import { readFileSync } from 'node:fs';
+import { readFile, writeFile, mkdir, rename } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getClaudeDir } from './paths.js';
+// Version-drift detection.
+//
+// Running an outdated claude-slim is not a cosmetic problem: v2.8.0 corrected
+// a startup estimate that earlier versions inflated ~8x, so a stale install
+// reports numbers that are simply wrong. Nothing told users they were behind —
+// this module closes that gap.
+//
+// It only *detects*. Updating is the package manager's job (`claude plugin
+// update`, `npm update -g`), and claude-slim writing into a directory the
+// plugin manager owns would be a good way to corrupt an install.
+//
+// NETWORK: this is the only outbound request claude-slim makes, and it is never
+// issued by `scan`/`clean`. It runs when the user explicitly asks (`doctor`,
+// `check-update`), fails open on any error, and caches for a day so repeated
+// invocations do not hammer the registry.
+const REGISTRY_URL = 'https://registry.npmjs.org/claude-slim/latest';
+const FETCH_TIMEOUT_MS = 2500;
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+function getCachePath() {
+    return join(getClaudeDir(), '.claude-slim-update-check.json');
+}
+/**
+ * Compare dotted numeric versions. Returns >0 if a is newer, <0 if b is newer.
+ * Pre-release suffixes (`-beta.1`) sort below the same release, matching semver
+ * closely enough for "is there something newer" without pulling in a dep.
+ */
+export function compareVersions(a, b) {
+    const split = (v) => {
+        const [core, ...rest] = v.trim().replace(/^v/, '').split('-');
+        return [core.split('.').map((n) => Number.parseInt(n, 10) || 0), rest.join('-')];
+    };
+    const [aNums, aPre] = split(a);
+    const [bNums, bPre] = split(b);
+    for (let i = 0; i < Math.max(aNums.length, bNums.length); i++) {
+        const diff = (aNums[i] ?? 0) - (bNums[i] ?? 0);
+        if (diff !== 0)
+            return diff;
+    }
+    if (aPre === bPre)
+        return 0;
+    if (!aPre)
+        return 1;
+    if (!bPre)
+        return -1;
+    return aPre < bPre ? -1 : 1;
+}
+/**
+ * Infer how this copy was installed from where it sits on disk, so the hint we
+ * print is the command that will actually work for this user.
+ */
+export function detectInstallMethod(modulePath) {
+    const p = modulePath.replace(/\\/g, '/');
+    if (p.includes('/.claude/plugins/'))
+        return 'plugin';
+    if (p.includes('/_npx/'))
+        return 'npx';
+    if (/\/(lib\/)?node_modules\/claude-slim\//.test(p))
+        return 'global';
+    if (p.includes('/dist/') || p.includes('/src/'))
+        return 'source';
+    return 'unknown';
+}
+export function upgradeCommandFor(method) {
+    switch (method) {
+        case 'plugin':
+            // `claude plugin update <name>` resolves plugin@marketplace ids; the bare
+            // name fails when the marketplace shares the plugin's name.
+            return 'claude plugin marketplace update claude-slim && claude plugin update claude-slim@claude-slim';
+        case 'global':
+            return 'npm install -g claude-slim@latest';
+        case 'npx':
+            // npx resolves latest per invocation, but a cached older copy can stick.
+            return 'npx claude-slim@latest';
+        case 'source':
+            return 'git pull && npm install';
+        default:
+            return null;
+    }
+}
+export function getInstalledVersion() {
+    try {
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+async function fetchLatestFromRegistry() {
+    try {
+        const res = await fetch(REGISTRY_URL, {
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+            headers: { accept: 'application/json' },
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.version === 'string' ? body.version : null;
+    }
+    catch {
+        // Offline, DNS failure, timeout, proxy, malformed JSON — all fail open.
+        return null;
+    }
+}
+async function readCache(path, now, ttlMs) {
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf-8'));
+        if (parsed.version !== 1)
+            return undefined;
+        if (now - parsed.checkedAt > ttlMs)
+            return undefined;
+        return parsed.latest;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeCache(path, now, latest) {
+    const tmp = `${path}.tmp`;
+    try {
+        await mkdir(dirname(path), { recursive: true });
+        const body = { version: 1, checkedAt: now, latest };
+        await writeFile(tmp, JSON.stringify(body));
+        await rename(tmp, path);
+    }
+    catch {
+        // A cache we cannot persist just means the next run checks again.
+    }
+}
+export async function checkForUpdate(opts = {}) {
+    const installed = opts.installed ?? getInstalledVersion();
+    const modulePath = opts.modulePath ?? fileURLToPath(import.meta.url);
+    const installMethod = detectInstallMethod(modulePath);
+    const cachePath = opts.cachePath ?? getCachePath();
+    const now = opts.now ?? Date.now();
+    const ttlMs = opts.ttlMs ?? CACHE_TTL_MS;
+    const fetchLatest = opts.fetchLatest ?? fetchLatestFromRegistry;
+    let latest;
+    let fromCache = false;
+    if (!opts.force) {
+        latest = await readCache(cachePath, now, ttlMs);
+        fromCache = latest !== undefined;
+    }
+    if (latest === undefined) {
+        // Defensive at the boundary: the built-in lookup already fails open, but a
+        // version check must never be able to take down `doctor`, whatever the
+        // injected fetcher does.
+        try {
+            latest = await fetchLatest();
+        }
+        catch {
+            latest = null;
+        }
+        await writeCache(cachePath, now, latest);
+    }
+    return {
+        installed,
+        latest: latest ?? null,
+        outdated: latest != null && compareVersions(latest, installed) > 0,
+        installMethod,
+        upgradeCommand: upgradeCommandFor(installMethod),
+        fromCache,
+    };
+}
+/** One-line human summary; null when there is nothing worth saying. */
+export function formatUpdateNotice(result) {
+    if (!result.outdated || result.latest === null)
+        return null;
+    const cmd = result.upgradeCommand ? `\n  → ${result.upgradeCommand}` : '';
+    return `claude-slim ${result.installed} is installed; ${result.latest} is available.${cmd}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-slim",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "description": "Audit and shrink your Claude Code startup context. Measures what every skill, plugin, agent, command, and memory file costs in the system prompt, then reversibly disables the dead weight. Non-destructive scan, tiered proposals, one-command restore — no proxy, no compression.",
   "type": "module",
   "bin": {

package/skills/claude-slim/SKILL.md

@@ -13,10 +13,38 @@ Analyze the user's Claude Code environment for token waste and perform non-destr
 - `/claude-slim scan` → report only, no changes
 - `/claude-slim scan --json` → raw JSON output
 - `/claude-slim doctor` → check scanner prerequisites and session-log signal quality
+- `/claude-slim check-update` → report whether a newer version is published
 - `/claude-slim restore` → restore previously disabled items
 
 ---
 
+## Phase 0 — Version gate (run before every scan)
+
+An outdated claude-slim does not merely lack features — it reports **wrong numbers**. Versions before 2.8.0 summed memory across every project on disk and inflated the startup estimate roughly 8×. Presenting those figures as fact is worse than not running at all, so check first:
+
+```bash
+cd "${CLAUDE_PLUGIN_ROOT}" && node dist/cli.js check-update --json
+```
+
+The check is cached for 24h and fails open — if it errors, times out, or returns `"latest": null`, **proceed silently**. Never block the user because a version lookup failed.
+
+If `"outdated": true`, stop and tell the user before scanning:
+
+> 설치된 claude-slim이 {installed}이고 최신은 {latest}입니다.
+> 2.8.0 이전 버전은 시작 토큰을 약 8배 부풀려 보고합니다 — 지금 스캔하면 그 숫자가 나옵니다.
+>
+> {upgradeCommand}
+>
+> 업데이트 후 진행할까요, 아니면 현재 버전으로 계속할까요?
+
+Then honour their answer. If they choose to continue, run the scan but **label the numbers as coming from an outdated version** in your report.
+
+**Plugin installs need a restart.** `claude plugin update` writes the new version to disk, but the running session keeps the loaded copy. Tell the user this explicitly — otherwise they update, re-run, and see the same stale numbers with no idea why.
+
+If `"outdated": false`, say nothing and continue to Phase 1.
+
+---
+
 ## Phase 1 — Scan
 
 Run the CLI to collect environment data: