claude-slim 2.7.1 → 2.7.3

package/README.md

@@ -211,58 +211,17 @@ From a real cleanup session:
 
 ---
 
-## v2.7 — What's new
-
-- **Unused-plugin detection** — claude-slim now reads your session transcripts for MCP tool calls (`mcp__plugin_<plugin>_<server>__*`) and slash commands, and flags plugins whose surfaces you've never touched in the last 60 days. Tier 3 (Optional, never auto-selected). When you choose to clean one, `claude plugin disable <name>` runs automatically; `/claude-slim restore` re-enables it.
-- **PLUGIN BREAKDOWN table** — the scan report now includes a per-plugin cost breakdown: token estimate (CLAUDE.md section + skills + deferred MCP tools + commands) and usage status (used / unused / agent-only / insufficient data / disabled). In the owner's real env: `oh-my-claudecode` tops the list at ~6,210 tok; three plugins were flagged as unused despite being enabled.
-- **Session parser fix** — slash commands in string-form user messages were previously missed (only array-form content was parsed). All slash-command invocations are now captured correctly.
-- **+82 tests** for the new modules and the parser regression.
-
-## v2.6 — What's new
-
-- **`claude-slim doctor`** — Checks Node support, `~/.claude/` readability, local skill/plugin cache access, `claude plugin list`, and recent session-log signal quality. Use it when scan results look sparse or unused-skill detection is suppressed.
-- **Clearer safety wording** — Skills and project memory are reversible moves into `~/.claude/skills.disabled/`; broken symlink files and failed-install `temp_local_*` caches are permanent cleanup targets and are labeled before selection.
-- **Pinned development Node version** — `.nvmrc` and `.node-version` pin contributors to Node 22.12.0, matching the current Vitest/Vite/Rolldown patch-floor requirements.
-
-## v2.4 — What's new
-
-- **Unused-skill detection** — claude-slim now reads your `~/.claude/projects/*/*.jsonl` session transcripts, finds every `Skill` tool invocation in the last 60 days, and flags local skills you've installed but never actually used. Tier 3 (Optional, never auto-selected) so you decide. Configurable lookback via `--lookback-days <n>`. Falls back silently if there's not enough session history (≥3 sessions required) — no false-flagging when the data source is unreliable.
-- **Plugin skills are intentionally out of scope** for this detector. They live inside `~/.claude/plugins/cache/` and are managed by the Claude Code plugin runtime; moving them would partially uninstall the plugin. Use `claude plugin disable <name>` for plugin-level cleanup.
-- **Per-file session-usage cache** at `~/.claude/.skill-usage-cache.json` keyed by mtime. Warm rescans only re-parse session logs that have changed.
-- **Node 20+** is now the engine floor (previously `>=18`, but Node 18 was already dropped from CI in v2.3.0).
-
-## v2.3 — What's new
-
-- **Detector registry refactor (v2.3.0)** — Scanner split from a 588-line module into focused detectors under `src/scanner/`. Adding a new heuristic is a one-function addition; see CONTRIBUTING.md. Public API unchanged.
-- **Path-containment guard (v2.2.3)** — Every destructive op refuses any target path that escapes `~/.claude/`. `runCommand` no longer goes through a shell. `temp_cache` cleanup is symlink-safe.
-- **Report sign fix (v2.2.3)** — The breakdown table's Saved column was inverted in earlier 2.2.x; cleanup now shows correct savings per row.
-- **85 tests (was 73)** — New round-trip coverage for path containment, restore guards, breakdown sign, restore-selection dedup, atomic tokenizer flush, and custom detector injection.
-
-## v2.2 — What's new
-
-- **Atomic `stale_project` clean/restore** — Single directory `rename()` instead of per-file loop. No more partial-failure state if the operation is interrupted.
-- **Clear collision errors** — Cleaning a project whose backup already exists (or restoring onto an existing directory) now fails with an actionable message instead of a cryptic OS error.
-- **Manifest schema v2** — Single JSON file (`manifest.json`) containing only currently-disabled entries. Restore removes the entry entirely, so the manifest stays bounded across many clean/restore cycles.
-- **Automatic migration from v1** — Existing legacy manifests (`.claude-slim-manifest.jsonl`) are auto-migrated on first read; the original is preserved as `.jsonl.bak` for safety.
-- **Crash-safe manifest writes** — Write-to-tmp-then-rename pattern prevents partial-write corruption on power loss or SIGKILL.
-- **Expanded test coverage** — 66 tests (was 35). New round-trip tests per issue type: `broken_symlink`, `template`, `duplicate`, `skill_dup`, `oversized_skill`, `temp_cache`, `stale_project`. Plus manifest migration + bounded-growth cycle tests.
-
-## v2.0 — What's new
-
-- **TypeScript CLI** — Rewritten from bash. Faster, more accurate, extensible.
-- **Accurate token counting** — [js-tiktoken](https://github.com/nicolo-ribaudo/js-tiktoken) with `cl100k_base` encoding.
-- **Savings report box** — Visual before/after with breakdown table and monthly savings estimate.
-- **`--dry-run`** — Preview changes without making them.
-- **`--json`** — Machine-readable output for automation.
-- **Token cache** — Instant repeat scans.
-- **Standalone CLI** — `npx claude-slim` works outside Claude Code.
-- **`--auto`** — Non-interactive cleanup for CI/scripts (Tier 1 only).
-- **Disabled plugin detection** — Finds plugins you disabled but didn't uninstall.
-- **Stale project detection** — Flags project memory untouched for 90+ days.
-- **CLAUDE.md section breakdown** — See which plugin instructions cost the most tokens.
-- **Plugin status** — Shows enabled/disabled status for each plugin.
-- **Non-TTY support** — Auto-selects Tier 1 when stdin is piped.
-- **Unit tests** — Vitest-based.
+## v2.7.2 — What's new
+
+Correctness patch fixing three HIGH-severity issues from a post-2.7.1 review. No new features; no breaking changes.
+
+- **Friendlier `unused_plugin` cleanup when the `claude` CLI is missing.** Users running claude-slim outside a Claude Code install used to see raw `spawn claude ENOENT` — one row per selected plugin. The cleaner now probes the CLI once up front via `isClaudeCliAvailable()`; failing items become `skipped` (not `errored`), and a single grouped warning points at the manual `claude plugin disable <name>` workaround.
+- **Nested-skill scanner now covers 3-deep layouts.** The prior 2-level walk silently missed `skills/<org>/<group>/<skill>/SKILL.md` — token totals under-reported and `unused_skill` could never flag them. Replaced with a bounded recursive walk (`MAX_SKILL_DEPTH = 3`) that stops descending once a `SKILL.md` is found, so nested docs under a declared skill don't become phantom duplicates.
+- **`scan --json` output contract locked in.** New test spies on `console.log` / `console.info` / `console.warn` during the full scan pipeline (both minimal and rich fixtures — session logs, plugin cache, memory, CLAUDE.md) and fails if any fires. No stray writes exist today; the invariant is now enforced so a future refactor can't silently break `claude-slim scan --json | jq`.
+
+Tests: 190 → 206 (+16).
+
+For older release notes, see [CHANGELOG.md](CHANGELOG.md).
 
 ---
 

package/dist/cleaner.d.ts

@@ -6,6 +6,12 @@ export interface CleanResult {
         name: string;
         error: string;
     }>;
+    /**
+     * Populated when one or more `unused_plugin` items were requested but the
+     * `claude` CLI is missing from PATH. The CLI surfaces this once at the top of
+     * the error block instead of N repeat rows.
+     */
+    claudeCliMissing?: boolean;
 }
 export declare function cleanIssues(issues: Issue[]): Promise<CleanResult>;
 export declare function restoreItem(entry: ManifestEntry | DisabledPluginEntry): Promise<void>;

package/dist/cleaner.js

@@ -2,7 +2,7 @@ import { rename, readdir, rmdir, rm, unlink, lstat, mkdir } from 'node:fs/promis
 import { join, dirname, resolve, sep } from 'node:path';
 import { appendManifest, ensureDisabledDir, getDisabledDir, removeEntry, recordDisabledPlugin, removeDisabledPlugin } from './manifest.js';
 import { assertInsideClaudeDir, getSkillsDir, getProjectsDir } from './paths.js';
-import { disablePlugin, enablePlugin } from './plugin-runtime.js';
+import { disablePlugin, enablePlugin, isClaudeCliAvailable, ClaudeCliMissingError } from './plugin-runtime.js';
 // Restrict a restore target to a specific subtree of ~/.claude/. Complements
 // assertInsideClaudeDir: a tampered manifest could still name a legal
 // ~/.claude/ path that belongs to a different type of asset (e.g. redirect a
@@ -45,6 +45,14 @@ export async function cleanIssues(issues) {
     const moved = [];
     const skipped = [];
     const errors = [];
+    // Pre-check: if any unused_plugin items are selected, verify `claude` CLI is
+    // reachable before we start. Failing fast with a single friendly message
+    // beats N raw ENOENTs mid-run. Skip the probe if no plugin items were picked.
+    const wantsPluginOps = issues.some((i) => i.type === 'unused_plugin');
+    let claudeCliMissing = false;
+    if (wantsPluginOps && !(await isClaudeCliAvailable())) {
+        claudeCliMissing = true;
+    }
     for (const issue of issues) {
         try {
             // unused_plugin and report-only types don't touch filesystem paths directly
@@ -132,6 +140,12 @@ export async function cleanIssues(issues) {
                 moved.push(entry);
             }
             else if (issue.type === 'unused_plugin') {
+                // Pre-check flagged `claude` missing — skip silently; the CLI prints
+                // one grouped message after cleanIssues returns.
+                if (claudeCliMissing) {
+                    skipped.push(issue.name);
+                    continue;
+                }
                 await disablePlugin(issue.name);
                 // Record in manifest; if that fails, roll back the disable
                 try {
@@ -150,13 +164,21 @@ export async function cleanIssues(issues) {
             }
         }
         catch (err) {
+            // Race window: `claude` was on PATH at pre-check but gone by the time we
+            // shelled out. Convert to the same grouped skip path instead of a raw
+            // ENOENT row.
+            if (err instanceof ClaudeCliMissingError) {
+                claudeCliMissing = true;
+                skipped.push(issue.name);
+                continue;
+            }
             const message = err instanceof Error ? err.message : String(err);
             errors.push({ name: issue.name, error: message });
         }
     }
     // Clean empty directories in skills/
     await cleanEmptyDirs(getSkillsDir());
-    return { moved, skipped, errors };
+    return { moved, skipped, errors, claudeCliMissing };
 }
 async function cleanEmptyDirs(dir) {
     try {

package/dist/cli.js

@@ -275,6 +275,12 @@ async function runCleanPipeline(opts) {
     console.log('');
     console.log(formatReportBox(reportData));
     console.log('');
+    if (cleanResult.claudeCliMissing) {
+        const skippedPluginCount = selectedIssues.filter((i) => i.type === 'unused_plugin').length;
+        console.log(`  \x1b[33m⚠ \`claude\` CLI not found on PATH — skipped ${skippedPluginCount} plugin(s).\x1b[0m`);
+        console.log('    Install Claude Code and re-run to disable unused plugins,');
+        console.log('    or disable them manually via `claude plugin disable <name>`.\n');
+    }
     if (cleanResult.errors.length > 0) {
         console.log('  \x1b[31mErrors:\x1b[0m');
         for (const err of cleanResult.errors) {

package/dist/plugin-runtime.d.ts

@@ -1,3 +1,18 @@
+/**
+ * Sentinel error class raised when the `claude` CLI is not on PATH.
+ * Callers (cleaner.ts) treat this as a "skip, don't error" condition so users
+ * running claude-slim outside a Claude Code install don't see a raw ENOENT
+ * mid-cleanup.
+ */
+export declare class ClaudeCliMissingError extends Error {
+    constructor();
+}
+/**
+ * Best-effort probe: is `claude` on PATH and answering `--version`?
+ * Never throws — a false result short-circuits `unused_plugin` cleanup with a
+ * friendly message rather than surfacing spawn ENOENT to end users.
+ */
+export declare function isClaudeCliAvailable(): Promise<boolean>;
 /** Validates plugin name then shells out to `claude plugin disable <name>`. */
 export declare function disablePlugin(name: string): Promise<void>;
 /** Validates plugin name then shells out to `claude plugin enable <name>`. */

package/dist/plugin-runtime.js

@@ -1,14 +1,43 @@
 import { execFile } from 'node:child_process';
 const PLUGIN_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+/**
+ * Sentinel error class raised when the `claude` CLI is not on PATH.
+ * Callers (cleaner.ts) treat this as a "skip, don't error" condition so users
+ * running claude-slim outside a Claude Code install don't see a raw ENOENT
+ * mid-cleanup.
+ */
+export class ClaudeCliMissingError extends Error {
+    constructor() {
+        super("`claude` CLI not found on PATH. Install Claude Code (https://claude.com/product/claude-code) " +
+            'to enable/disable plugins, or run `claude-slim clean` without the unused-plugin items selected.');
+        this.name = 'ClaudeCliMissingError';
+    }
+}
 function validateName(name) {
     if (!PLUGIN_NAME_RE.test(name)) {
         throw new Error(`Refusing to operate on suspicious plugin name: ${name}`);
     }
 }
+/**
+ * Detects the classic "binary missing from PATH" shape of Node's execFile error.
+ * spawn ENOENT surfaces as an Error with { code: 'ENOENT', syscall: 'spawn claude' }.
+ * The exact-match on `spawn claude` avoids false positives for hypothetical
+ * sibling binaries (e.g. `claude-code`) that might be spawned by future code.
+ */
+function isClaudeMissing(err) {
+    if (!(err instanceof Error))
+        return false;
+    const e = err;
+    return e.code === 'ENOENT' && e.syscall === 'spawn claude';
+}
 function runPluginCommand(subcommand, name) {
     return new Promise((resolve, reject) => {
         execFile('claude', ['plugin', subcommand, name], { timeout: 30000 }, (err, _stdout, stderr) => {
             if (err) {
+                if (isClaudeMissing(err)) {
+                    reject(new ClaudeCliMissingError());
+                    return;
+                }
                 const detail = stderr?.trim() ? `: ${stderr.trim()}` : '';
                 reject(new Error(`${err.message}${detail}`));
                 return;
@@ -21,6 +50,18 @@ function runPluginCommand(subcommand, name) {
         });
     });
 }
+/**
+ * Best-effort probe: is `claude` on PATH and answering `--version`?
+ * Never throws — a false result short-circuits `unused_plugin` cleanup with a
+ * friendly message rather than surfacing spawn ENOENT to end users.
+ */
+export function isClaudeCliAvailable() {
+    return new Promise((resolve) => {
+        execFile('claude', ['--version'], { timeout: 5000 }, (err) => {
+            resolve(!err);
+        });
+    });
+}
 /** Validates plugin name then shells out to `claude plugin disable <name>`. */
 export async function disablePlugin(name) {
     validateName(name);

package/dist/scanner/index.js

@@ -1,3 +1,8 @@
+// INVARIANT: nothing in the scanner (this file or anything under scanner/**)
+// may write to stdout. The CLI pipes stdout of `scan --json` to jq/other
+// tools; a stray console.log would silently corrupt machine-readable output.
+// Route diagnostics through console.error. Enforced by
+// src/__tests__/scan-stdout-invariant.test.ts.
 import { join } from 'node:path';
 import { countTokensCached } from '../tokenizer.js';
 import { getClaudeDir } from '../paths.js';

package/dist/scanner/local-skills.js

@@ -20,24 +20,30 @@ export function dedupeBySymlink(candidates) {
     }
     return Array.from(seen.values());
 }
+// Max depth for the nested-skill walk. Depth 1 = ~/.claude/skills/<a>/SKILL.md,
+// depth 2 = ~/.claude/skills/<a>/<b>/SKILL.md, etc. Depth 3 covers the deepest
+// layouts seen in the wild (e.g. plugin-namespaced groups like
+// skills/<org>/<group>/<skill>/SKILL.md) while keeping the walk finite.
+// If a directory contains a SKILL.md we stop descending — nested SKILL.md
+// files under an already-declared skill would just create phantom duplicates.
+const MAX_SKILL_DEPTH = 3;
 export async function scanLocalSkills() {
     const skillsDir = getSkillsDir();
     const candidates = [];
     const brokenSymlinks = [];
     const contents = new Map();
-    const entries = await safeReaddir(skillsDir);
-    const scanPromises = entries.map(async (entry) => {
-        const dirPath = join(skillsDir, entry);
-        if (!(await isDirectory(dirPath)))
+    async function visit(dirPath, nameParts, depth) {
+        if (depth > MAX_SKILL_DEPTH)
             return;
         const skillMd = join(dirPath, 'SKILL.md');
+        const displayName = nameParts.join('/');
         if (await isBrokenSymlink(skillMd)) {
             let target = 'unknown';
             try {
                 target = await readlink(skillMd);
             }
             catch { /* */ }
-            brokenSymlinks.push({ name: entry, path: skillMd, target });
+            brokenSymlinks.push({ name: displayName, path: skillMd, target });
             return;
         }
         const content = await safeReadFile(skillMd);
@@ -47,7 +53,7 @@ export async function scanLocalSkills() {
             const realMdPath = await resolveRealPath(skillMd);
             candidates.push({
                 skill: {
-                    name: entry,
+                    name: displayName,
                     path: dirPath,
                     sizeBytes: Buffer.byteLength(content),
                     tokens,
@@ -55,43 +61,31 @@ export async function scanLocalSkills() {
                 },
                 realMdPath,
             });
+            // Stop descending: nested SKILL.md files under a declared skill are
+            // documentation/examples, not addressable skills.
+            return;
         }
-        // Nested skills (e.g., @internal-sys/commit-guide)
+        if (depth === MAX_SKILL_DEPTH)
+            return;
         const subEntries = await safeReaddir(dirPath);
-        for (const sub of subEntries) {
+        await Promise.all(subEntries.map(async (sub) => {
             const subDir = join(dirPath, sub);
+            // isDirectory() uses stat(), which follows symlinks — intentional so
+            // users can symlink shared skills into ~/.claude/skills/. A cycle
+            // through symlinks would be bounded by MAX_SKILL_DEPTH, not by us
+            // detecting the loop directly.
             if (!(await isDirectory(subDir)))
-                continue;
-            const subSkillMd = join(subDir, 'SKILL.md');
-            if (await isBrokenSymlink(subSkillMd)) {
-                let target = 'unknown';
-                try {
-                    target = await readlink(subSkillMd);
-                }
-                catch { /* */ }
-                brokenSymlinks.push({ name: `${entry}/${sub}`, path: subSkillMd, target });
-                continue;
-            }
-            const subContent = await safeReadFile(subSkillMd);
-            if (subContent !== null) {
-                const name = `${entry}/${sub}`;
-                contents.set(subSkillMd, subContent);
-                const tokens = countTokensCached(subContent, subSkillMd);
-                const realMdPath = await resolveRealPath(subSkillMd);
-                candidates.push({
-                    skill: {
-                        name,
-                        path: subDir,
-                        sizeBytes: Buffer.byteLength(subContent),
-                        tokens,
-                        source: 'local',
-                    },
-                    realMdPath,
-                });
-            }
-        }
-    });
-    await Promise.all(scanPromises);
+                return;
+            await visit(subDir, [...nameParts, sub], depth + 1);
+        }));
+    }
+    const topEntries = await safeReaddir(skillsDir);
+    await Promise.all(topEntries.map(async (entry) => {
+        const dirPath = join(skillsDir, entry);
+        if (!(await isDirectory(dirPath)))
+            return;
+        await visit(dirPath, [entry], 1);
+    }));
     const skills = dedupeBySymlink(candidates);
     return { skills, brokenSymlinks, contents };
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-slim",
-  "version": "2.7.1",
-  "description": "Analyze and reduce Claude Code token overhead",
+  "version": "2.7.3",
+  "description": "Cut Claude Code startup token overhead — non-destructive scan, tiered proposals, one-command restore. Finds unused skills, duplicate registrations, stale memory, and heavyweight plugins in ~/.claude/.",
   "type": "module",
   "bin": {
     "claude-slim": "./dist/cli.js"
@@ -23,11 +23,19 @@
   "keywords": [
     "claude",
     "claude-code",
+    "anthropic",
     "token",
-    "optimization",
+    "token-optimization",
+    "context-bloat",
+    "prompt-optimization",
+    "system-prompt",
     "cleanup",
     "skills",
-    "plugin"
+    "skill-management",
+    "plugin",
+    "plugin-cleanup",
+    "cli",
+    "developer-experience"
   ],
   "author": "iops-leo",
   "license": "MIT",