claude-slim 2.8.1 → 2.9.1

package/README.md

@@ -149,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
 ```
 
@@ -161,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
@@ -228,17 +245,14 @@ Token counts come from [js-tiktoken](https://github.com/nicolo-ribaudo/js-tiktok
 
 ---
 
-## v2.8.0 — What's new
+## v2.9.1 — What's new
 
-Accuracy release. Three reported numbers were wrong; the largest was wrong by an order of magnitude. **If your startup estimate drops sharply after upgrading, the old number was the inaccurate one.**
+Found while stress-testing the scanner against deliberately hostile `~/.claude` fixtures.
 
-- **Startup estimate no longer sums memory across every project on disk.** Claude Code loads `~/.claude/projects/<slug>/memory/` for the project you're in — not the other 40 project directories in your `~/.claude`. The old total scaled with how many projects you'd ever opened: on the dev machine it reported **116,259 tokens where the real per-session cost was 14,399**. Now scoped to the current project, with the cross-project total still shown and labelled as not a per-session cost.
-- **Skill listing cost is measured, not assumed.** Each skill adds a `- <name>: <description>` line to the system prompt. The flat 30-tokens-per-skill estimate stood in for all of them; measured across 68 installed skills the real spread is **30 → 509 tokens (mean 51)**. The per-plugin cost gradient can now tell five terse skills apart from five verbose ones.
-- **`~/.claude/agents/` and `~/.claude/commands/` are now scanned.** Previously invisible despite loading into every session — 12 agents worth ~2,254 tokens on the dev machine. Reported only; never moved or deleted, because there's no restore path for them yet.
-- **Fixed: plugin manifests were stuck at 2.7.0 for three releases**, so `claude plugin install` advertised a stale version. CI now fails on version drift.
-- **Fixed: the token cache grew without bound** — 355 of 776 entries (46%) pointed at deleted files. `flushCache()` now prunes them.
+- **Fixed: `scan` could hang forever on a single long line.** js-tiktoken's BPE is quadratic in the length of one whitespace-free run. Normal prose is fine (8,000 characters encodes in ~1ms), but 800 characters of Hangul cost ~450ms, 3,200 cost ~6.8s, and a 60,000-character run wedged `scan` past 20 seconds with **no output at all** — indistinguishable from a freeze. `SKILL.md` files hit this via base64 blobs, minified snippets, embedded JSON schemas, and CJK text. Long runs are now estimated by encoding a bounded prefix and scaling; **files without one produce byte-identical counts** (verified across 71 installed skills: 70 exact, one moved 0.01%). Hostile fixture: 20s+ → 1.78s, with no measurable cost on ordinary input.
+- **Fixed: a mistyped subcommand blamed the wrong thing.** `claude-slim scam` printed `error: too many arguments. Expected 0 arguments but got 1`. It now names the unknown command and lists the real ones.
 
-Tests: 206 → 241 (+35).
+Tests: 266 → 279 (+13).
 
 For older release notes, see [CHANGELOG.md](CHANGELOG.md).
 

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')
@@ -216,7 +244,21 @@ program
     await flushCache();
 });
 // --- default (no subcommand) → run clean ---
+// Because the program itself carries an action, commander routes a mistyped
+// subcommand here and reports its own "too many arguments. Expected 0 arguments
+// but got 1" — which says nothing about what the user actually got wrong.
+// Accept the excess argument so we can name it instead.
+program.allowExcessArguments(true);
 program.action(async () => {
+    const stray = program.args;
+    if (stray.length > 0) {
+        const names = program.commands.map((c) => c.name()).join(', ');
+        console.error(`error: unknown command '${stray[0]}'`);
+        console.error(`available commands: ${names}`);
+        console.error(`run 'claude-slim --help' for usage`);
+        process.exitCode = 1;
+        return;
+    }
     await runCleanPipeline({ dryRun: false, auto: false, sessionsPerDay: 2, lookbackDays: 60 });
 });
 // --- shared clean pipeline ---

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

@@ -39,11 +39,72 @@ export async function initTokenizer() {
 function hashContent(content) {
     return createHash('md5').update(content).digest('hex');
 }
+// js-tiktoken's BPE is quadratic in the length of a single whitespace-free run.
+// Ordinary prose of any length is fine — the pre-tokenizer splits on whitespace,
+// so 8,000 characters of normal text encodes in ~1ms. One long unbroken run does
+// not: measured on cl100k_base, 800 characters of Hangul costs ~450ms, 3,200
+// costs ~6.8s, and a 60,000-character run wedges the scan for minutes with no
+// output at all. Real SKILL.md files reach this with base64 blobs, minified
+// snippets, rule separators, and CJK text.
+//
+// 512 sits above anything a normal word, path, or URL produces and well below
+// where the curve turns painful.
+const MAX_ENCODE_RUN = 512;
+const LONG_RUN_PATTERN = /\S{513,}/;
+const FALLBACK_CHARS_PER_TOKEN = 4;
+/**
+ * Estimate an over-long run by encoding a bounded prefix and scaling.
+ *
+ * A fixed characters-per-token divisor cannot work here: measured over 1,000-char
+ * runs, cl100k_base yields 0.8 chars/token for Hangul but 8.0 for a repeated
+ * ASCII character — a 10× spread. Sampling the run's own prefix adapts to
+ * whatever it actually contains (base64, hex, minified JSON, CJK) at the cost of
+ * exactly one bounded encode.
+ */
+function estimateRun(segment, encode) {
+    const sample = segment.slice(0, MAX_ENCODE_RUN);
+    const sampleTokens = encode(sample).length;
+    if (sampleTokens === 0)
+        return 0;
+    return Math.ceil((sampleTokens * segment.length) / sample.length);
+}
+/**
+ * Encode `text`, estimating any whitespace-free run longer than
+ * {@link MAX_ENCODE_RUN} instead of feeding the whole run to the BPE.
+ *
+ * Text without such a run takes the fast path and is encoded whole, so counts
+ * for well-formed files are identical to encoding directly.
+ */
+function encodeBounded(text, encode) {
+    if (!LONG_RUN_PATTERN.test(text)) {
+        return encode(text).length;
+    }
+    let total = 0;
+    let buffered = '';
+    // Splitting on a captured group keeps the whitespace in the stream, so the
+    // buffered pieces still look to the encoder like the original text.
+    for (const segment of text.split(/(\s+)/)) {
+        if (segment.length > MAX_ENCODE_RUN) {
+            if (buffered) {
+                total += encode(buffered).length;
+                buffered = '';
+            }
+            total += estimateRun(segment, encode);
+            continue;
+        }
+        buffered += segment;
+    }
+    if (buffered) {
+        total += encode(buffered).length;
+    }
+    return total;
+}
 export function countTokens(text) {
     if (useFallback || !encoder) {
-        return Math.ceil(text.length / 4);
+        return Math.ceil(text.length / FALLBACK_CHARS_PER_TOKEN);
     }
-    return encoder.encode(text).length;
+    const enc = encoder;
+    return encodeBounded(text, (s) => enc.encode(s));
 }
 export function countTokensCached(text, filePath) {
     const hash = hashContent(text);

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.1",
+  "version": "2.9.1",
   "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: