claude-slim 2.12.1 → 2.13.0

package/README.md

@@ -148,6 +148,7 @@ Then just type `/claude-slim` in any session.
 /claude-slim scan                     # Report only, no changes
 /claude-slim scan --json              # Machine-readable JSON output
 /claude-slim scan --lookback-days 30  # Treat skills idle for 30+ days as unused
+/claude-slim scan --project-dir PATH  # Count PATH's project memory (default: cwd)
 /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
@@ -248,12 +249,15 @@ Token counts come from [js-tiktoken](https://github.com/nicolo-ribaudo/js-tiktok
 
 ---
 
-## v2.12.1 — What's new
+## v2.13.0 — What's new
 
-- **Fixed: the `/claude-slim` skill reported project memory as zero.** It invoked the CLI with `cd "${CLAUDE_PLUGIN_ROOT}"`, making `cwd` the plugin cache directory; the project slug resolved there, matched nothing, and every project-memory token silently left the startup total — **108,570** on the machine where this surfaced. `SKILL.md` no longer `cd`s. This hit the tool's primary entry point, and quietly: a zero reads as a clean result.
-- **`--project-dir <path>`** for callers that cannot run from the project directory, plus a warning when the CLI notices it is running from its own install without one.
+- **Changed: the startup estimate no longer counts disabled plugins.** Their skills are not in the session catalog, so they are not a startup cost — but they were being added to a number labelled "tokens at session start". Verified against a live session rather than assumed: skills from every disabled plugin were absent from the prompt, while every enabled one's were present. Measured here: **12,504 → 9,836**, a 21% correction.
+- **Added `disabledPluginSkillTokens`**, shown under the overhead line and in `--json` — what re-enabling everything would cost. A headline number that drops by a fifth with no explanation reads like a bug.
+- **Fixed: plugin skills are attributed to their plugin, not their marketplace.** One marketplace can host several plugins with different enabled states, so the two had to be told apart.
 
-Tests: 392 → 401 (+9).
+Only plugins *explicitly reported disabled* are excluded. `claude plugin list` has a third state — `✘ failed to load` — and a plugin in it still loads its skills, so anything unrecognised keeps counting.
+
+Tests: 452 → 461 (+9).
 
 For older release notes, see [CHANGELOG.md](CHANGELOG.md).
 

package/dist/cleaner.js

@@ -3,6 +3,16 @@ import { join, dirname, resolve, sep } from 'node:path';
 import { appendManifest, ensureDisabledDir, removeEntry, recordDisabledPlugin, removeDisabledPlugin } from './manifest.js';
 import { assertInsideAgentRoot, getAgentRoot, getAgentDisabledDir, getSkillsDir, getProjectsDir } from './paths.js';
 import { disablePlugin, enablePlugin, isClaudeCliAvailable, ClaudeCliMissingError } from './plugin-runtime.js';
+/**
+ * Issue types whose cleanup consumes a filesystem path — the ones where two
+ * findings on the same path cannot both be executed. Types absent here are
+ * either report-only (`oversized_memory`, `disabled_plugin`) or addressed by
+ * name through the `claude` CLI rather than by path (`unused_plugin`).
+ */
+const MOVES_A_PATH = new Set([
+    'template', 'duplicate', 'skill_dup', 'oversized_skill', 'unused_skill',
+    'backup_artifact', 'broken_symlink', 'temp_cache', 'stale_project',
+]);
 // 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
@@ -51,7 +61,25 @@ export async function cleanIssues(issues) {
     if (wantsPluginOps && !(await isClaudeCliAvailable())) {
         claudeCliMissing = true;
     }
+    // The detectors run independently, so one skill routinely earns several
+    // findings at once — `skillify` shows up as duplicate + oversized_skill +
+    // unused_skill. Selecting "all" then tried to rename the same directory three
+    // times: the first succeeded and the rest surfaced raw ENOENT rows, telling
+    // the user a cleanup had failed when it had in fact worked. Collapse them
+    // here, keeping the first (issues arrive tier-ordered, so that is the
+    // most-confident finding for the path).
+    const deduped = [];
+    const claimedPaths = new Set();
     for (const issue of issues) {
+        if (MOVES_A_PATH.has(issue.type)) {
+            const key = `${issue.agent ?? 'claude'}:${issue.path}`;
+            if (claimedPaths.has(key))
+                continue;
+            claimedPaths.add(key);
+        }
+        deduped.push(issue);
+    }
+    for (const issue of deduped) {
         // Scope every path decision to the issue's own agent, so a Codex issue can
         // never resolve into ~/.claude/ (or the reverse).
         const agent = issue.agent ?? 'claude';

package/dist/cli.js

@@ -10,13 +10,13 @@ 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 { looksLikeToolInstallDir } from './paths.js';
+import { looksLikeToolInstallDir, projectDirError } from './paths.js';
 import { checkForUpdate, formatUpdateNotice } from './update-check.js';
 import { confirmDecision, planUpdate, renderStep, runUpdate } from './update-run.js';
 import { scanCodex } from './codex/index.js';
 import { formatCodexSummary } from './codex/report.js';
 import { classifyCodexIssues } from './codex/detectors.js';
-import { resolveSelection, resolveRestoreSelection } from './selection.js';
+import { resolveSelection, resolveRestoreSelection, parseSelection } from './selection.js';
 const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
 const { version: PKG_VERSION } = JSON.parse(readFileSync(pkgPath, 'utf-8'));
 // Parse a non-negative-integer CLI option, keeping explicit 0 distinct from an
@@ -254,7 +254,8 @@ program
         return;
     }
     console.log('');
-    const selection = await askUser('  Restore (all / numbers / none): ');
+    const selection = await askUser('  Restore (all / numbers / ranges / none): ');
+    warnIgnoredSelection(selection, restorable.length);
     const indices = resolveRestoreSelection(selection, restorable.length);
     if (indices.length === 0) {
         console.log('\n  Cancelled.\n');
@@ -284,9 +285,17 @@ program
     .description('Show savings report from last clean')
     .option('--sessions-per-day <n>', 'Sessions per day for savings estimate', '2')
     .option('--lookback-days <n>', 'Days of session history for skill-usage analysis', '60')
+    .option('--project-dir <path>', 'Directory whose project memory counts toward the total (default: cwd)')
     .action(async (opts) => {
     await initTokenizer();
-    const result = await scan({ lookbackDays: parseNonNegativeInt(opts.lookbackDays, 60) });
+    // Must resolve the same way `scan` and `clean` do. Skipping this left
+    // `report` as the one command that would neither honour --project-dir nor
+    // warn from an install directory, so its before/after pair could be
+    // computed against a different project than the clean it is reporting on.
+    const result = await scan({
+        lookbackDays: parseNonNegativeInt(opts.lookbackDays, 60),
+        projectDir: resolveProjectDir(opts.projectDir),
+    });
     const allEntries = await readManifest();
     // Filter to legacy-style entries only (those with tokenCount/name/from fields)
     const entries = allEntries.filter((e) => !('plugin' in e && 'marketplace' in e));
@@ -358,6 +367,24 @@ program.action(async () => {
     }
     await runCleanPipeline({ dryRun: false, auto: false, sessionsPerDay: 2, lookbackDays: 60, codex: true });
 });
+/**
+ * Name the fragments of a selection that were thrown away.
+ *
+ * Silence here is dangerous in one direction only: the user believes they
+ * selected more than they did, sees a short confirmation, and assumes the rest
+ * is coming. Keywords (`all`, `none`, empty) are handled by the resolvers and
+ * are not fragments, so they are not reported as invalid.
+ */
+function warnIgnoredSelection(input, count) {
+    const trimmed = input.trim().toLowerCase();
+    if (trimmed === '' || ['all', 'a', 'none', 'n', 'enter'].includes(trimmed))
+        return;
+    const { invalid } = parseSelection(trimmed, count);
+    if (invalid.length === 0)
+        return;
+    console.log(`  \x1b[33m!\x1b[0m Ignored ${invalid.length} unrecognised entr${invalid.length === 1 ? 'y' : 'ies'}: ` +
+        `${invalid.join(', ')}  \x1b[90m(valid: 1-${count}, e.g. "3", "5-12")\x1b[0m`);
+}
 /**
  * Resolve which directory's project memory counts toward the startup estimate.
  *
@@ -365,10 +392,24 @@ program.action(async () => {
  * directory was given: the slug would resolve to the plugin cache, match no
  * project, and silently zero out every project-memory token. Warning beats
  * guessing — we cannot know which project the user meant.
+ *
+ * A `--project-dir` that does not exist is a hard error rather than a warning.
+ * The slug is derived from the path string, so a typo happily resolves to a
+ * slug that matches nothing and reports 0 — reintroducing, through the very
+ * flag added to prevent it, the silent zero of v2.12.1. An explicit flag with a
+ * bad value is unambiguously a mistake, so fail instead of guessing.
  */
 function resolveProjectDir(explicit) {
-    if (explicit)
+    if (explicit) {
+        const err = projectDirError(explicit);
+        if (err) {
+            // Exit rather than fall back to cwd: continuing would print a full,
+            // confident report built on the wrong project.
+            console.error(`error: ${err}`);
+            process.exit(1);
+        }
         return explicit;
+    }
     if (looksLikeToolInstallDir()) {
         console.error('  \x1b[33m!\x1b[0m Running from claude-slim\'s own install directory, so project memory\n' +
             '    cannot be attributed and is reported as 0. Pass --project-dir <path>\n' +
@@ -400,10 +441,12 @@ async function runCleanPipeline(opts) {
         console.log('  Actions:');
         console.log('    Enter    → accept pre-selected (Tier 1 only)');
         console.log('    1,3,5    → select specific items');
+        console.log('    1-9      → select a range');
         console.log('    all      → select everything');
         console.log('    none     → cancel');
         console.log('');
         const selection = await askUser('  Your choice: ');
+        warnIgnoredSelection(selection, result.issues.length);
         selectedIssues = resolveSelection(selection, result.issues);
     }
     else if (opts.auto) {

package/dist/paths.d.ts

@@ -23,6 +23,19 @@ export declare function getCurrentProjectSlug(cwd?: string): string;
  * `--project-dir` instead of quietly reporting zero.
  */
 export declare function looksLikeToolInstallDir(cwd?: string): boolean;
+/**
+ * Why an explicit `--project-dir` is unusable, or null when it is fine.
+ *
+ * The slug is a pure string transform of the path, so a typo resolves to a
+ * perfectly well-formed slug that matches no project on disk and reports zero
+ * project memory. That is the identical silent zero v2.12.1 was cut to fix,
+ * reintroduced through the flag added to fix it. A non-existent explicit path
+ * is unambiguously a mistake — worth an error, not a guess.
+ *
+ * A directory that exists but holds no memory is NOT an error: that is a real,
+ * correctly-measured zero.
+ */
+export declare function projectDirError(p: string): string | null;
 export declare function getManifestPath(): string;
 export declare function getLegacyManifestPath(): string;
 /** The agents claude-slim is allowed to touch. Adding one widens what every

package/dist/paths.js

@@ -1,4 +1,5 @@
 import { homedir } from 'node:os';
+import { statSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
 export function getClaudeDir() {
     return join(homedir(), '.claude');
@@ -42,6 +43,30 @@ export function looksLikeToolInstallDir(cwd = process.cwd()) {
         p.includes('/_npx/') ||
         /\/node_modules\/claude-slim(\/|$)/.test(p));
 }
+/**
+ * Why an explicit `--project-dir` is unusable, or null when it is fine.
+ *
+ * The slug is a pure string transform of the path, so a typo resolves to a
+ * perfectly well-formed slug that matches no project on disk and reports zero
+ * project memory. That is the identical silent zero v2.12.1 was cut to fix,
+ * reintroduced through the flag added to fix it. A non-existent explicit path
+ * is unambiguously a mistake — worth an error, not a guess.
+ *
+ * A directory that exists but holds no memory is NOT an error: that is a real,
+ * correctly-measured zero.
+ */
+export function projectDirError(p) {
+    let st;
+    try {
+        st = statSync(p);
+    }
+    catch {
+        return `--project-dir is not an existing directory: ${p}`;
+    }
+    if (!st.isDirectory())
+        return `--project-dir is not a directory: ${p}`;
+    return null;
+}
 export function getManifestPath() {
     return join(getDisabledDir(), 'manifest.json');
 }

package/dist/report.js

@@ -74,8 +74,11 @@ export function formatReportBox(data) {
         const visible = s.replace(/\x1b\[[0-9;]*m/g, '');
         return s + ' '.repeat(Math.max(0, W - 2 - visible.length));
     };
-    const top = '\u256d' + '\u2500'.repeat(W) + '\u256e';
-    const bot = '\u2570' + '\u2500'.repeat(W) + '\u256f';
+    // W is the total line width, so the run between the corners is W - 2 \u2014 the
+    // same interior width `pad()` and `blank` use. Repeating W here made every
+    // border overhang its own body by two columns.
+    const top = '\u256d' + '\u2500'.repeat(W - 2) + '\u256e';
+    const bot = '\u2570' + '\u2500'.repeat(W - 2) + '\u256f';
     const blank = '\u2502' + ' '.repeat(W - 2) + '\u2502';
     lines.push(top);
     lines.push(`\u2502${pad('  claude-slim report')}\u2502`);
@@ -203,6 +206,16 @@ export function formatScanSummary(result) {
             `${result.currentProjectMemoryTokens.toLocaleString()} tok  ` +
             `\x1b[90m(${result.allProjectsMemoryTokens.toLocaleString()} tok across all projects, ` +
             `not a per-session cost)\x1b[0m`);
+        // Zero reads as "clean", so name the reason for it. Deliberately does not
+        // claim the memory is unattributed: a directory Claude has simply never
+        // opened has no memory, and that 0 is correct. What is worth surfacing is
+        // that no project state backs this path, so if the user meant a different
+        // project, this total is answering the wrong question.
+        if (!result.currentProjectKnown) {
+            lines.push(`    \x1b[33m!\x1b[0m No Claude project state for \x1b[90m${result.currentProjectSlug}\x1b[0m — ` +
+                `nothing to attribute here.\n` +
+                `      \x1b[90mIf you meant a different project, pass --project-dir <path>.\x1b[0m`);
+        }
     }
     // --- MCP SERVERS ---
     lines.push('');
@@ -238,6 +251,20 @@ export function formatScanSummary(result) {
     // --- SUMMARY ---
     lines.push('');
     lines.push(`\x1b[1m  ESTIMATED OVERHEAD\x1b[0m: ~${result.totalTokensBefore.toLocaleString()} tokens at session start`);
+    if (result.disabledPluginSkillTokens > 0) {
+        // Stated rather than silently omitted: the figure moved out of the total in
+        // 2.13.0, and a total that drops with no explanation reads like a bug.
+        lines.push(`  \x1b[90mexcludes ~${result.disabledPluginSkillTokens.toLocaleString()} tokens of disabled-plugin skills — ` +
+            `not loaded, so not a startup cost\x1b[0m`);
+    }
+    if (result.issues.length > 0) {
+        // Stated next to the total it is a fraction of, because the numbers on the
+        // issue rows below are body sizes, not startup cost, and adding them up
+        // yields a "saving" many times larger than the whole startup budget.
+        lines.push(`  \x1b[1mRECOVERABLE\x1b[0m: ~${result.recoverableStartupTokens.toLocaleString()} tokens ` +
+            `\x1b[90mif every issue below is acted on (startup cost only — the per-issue\n` +
+            `  figures below are full file sizes, paid when a skill runs, not at startup)\x1b[0m`);
+    }
     if (isUsingFallback()) {
         lines.push(`  \x1b[33m\u26a0 Using bytes/4 approximation (js-tiktoken unavailable)\x1b[0m`);
     }

package/dist/scanner/fs-walk.d.ts

@@ -1,6 +1,9 @@
+import type { Stats } from 'node:fs';
 export declare function safeReadFile(p: string): Promise<string | null>;
 export declare function safeReaddir(p: string): Promise<string[]>;
 export declare function isDirectory(p: string): Promise<boolean>;
+/** Stats `p`, or null when it cannot be read. Follows symlinks, like isDirectory. */
+export declare function safeStat(p: string): Promise<Stats | null>;
 export declare function isBrokenSymlink(p: string): Promise<boolean>;
 export declare function resolveRealPath(p: string): Promise<string>;
 export declare function getDirSize(dir: string): Promise<number>;

package/dist/scanner/fs-walk.js

@@ -24,6 +24,15 @@ export async function isDirectory(p) {
         return false;
     }
 }
+/** Stats `p`, or null when it cannot be read. Follows symlinks, like isDirectory. */
+export async function safeStat(p) {
+    try {
+        return await stat(p);
+    }
+    catch {
+        return null;
+    }
+}
 export async function isBrokenSymlink(p) {
     try {
         const lstats = await lstat(p);

package/dist/scanner/index.d.ts

@@ -1,4 +1,4 @@
-import type { ScanResult } from '../types.js';
+import type { Issue, ScanResult, SkillInfo } from '../types.js';
 export interface ScanOptions {
     lookbackDays?: number;
     /**
@@ -12,3 +12,26 @@ export interface ScanOptions {
     projectDir?: string;
 }
 export declare function scan(opts?: ScanOptions): Promise<ScanResult>;
+/**
+ * What acting on every issue would actually save at session start.
+ *
+ * Two corrections over a naive `sum(issues.tokens)`, both of which inflate:
+ *
+ * - **Per-path, not per-issue.** The detectors are independent, so one skill
+ *   routinely earns several findings at once (`duplicate` + `oversized_skill` +
+ *   `unused_skill`). Removing it once collects the saving once.
+ * - **Listing tokens, not body tokens.** `Issue.tokens` is the whole SKILL.md,
+ *   which is loaded only when the skill runs. Startup pays for the catalog
+ *   line alone. Conflating the two overstated savings ~80× in practice.
+ *
+ * Memory issues count only when they belong to the current project — the same
+ * per-project rule `totalTokensBefore` follows. Deletions that free disk but no
+ * context (`broken_symlink`, `temp_cache`) contribute nothing here by design.
+ *
+ * Three separate overlaps have to be collapsed, since every one of them inflates:
+ * the same skill path, the same plugin across cached versions, and a memory file
+ * that its own stale project already accounts for.
+ */
+export declare function sumRecoverableStartupTokens(issues: Issue[], skills: SkillInfo[], currentProjectSlug: string, 
+/** Plugin name → its skill-listing tokens. See the `unused_plugin` branch. */
+pluginSkillListingTokens?: Map<string, number>): number;

package/dist/scanner/index.js

@@ -4,8 +4,9 @@
 // Route diagnostics through console.error. Enforced by
 // src/__tests__/scan-stdout-invariant.test.ts.
 import { join } from 'node:path';
+import { access } from 'node:fs/promises';
 import { countTokensCached } from '../tokenizer.js';
-import { getClaudeDir, getCurrentProjectSlug } from '../paths.js';
+import { getClaudeDir, getCurrentProjectSlug, getProjectsDir } from '../paths.js';
 import { safeReadFile } from './fs-walk.js';
 import { scanLocalSkills } from './local-skills.js';
 import { scanPluginSkills } from './plugin-skills.js';
@@ -89,7 +90,39 @@ export async function scan(opts = {}) {
     // measured from each file's frontmatter description rather than assumed
     // (see scanner/skill-listing.ts) — the real spread is 30–500+ tokens apiece.
     const sumListing = (entries) => entries.reduce((sum, e) => sum + e.listingTokens, 0);
-    const skillListingTokens = sumListing(localSkills) + sumListing(pluginSkills);
+    // A disabled plugin's skills are not in the session catalog, so they cost
+    // nothing at startup. Verified against a live session: skills from every
+    // disabled plugin here (document-skills, superpowers, telegram, …) were
+    // absent from the prompt, while enabled ones were present. Counting them put
+    // 3,397 tokens — 27% of the total — into a number labelled "at session start".
+    //
+    // Only names reported *explicitly disabled* are dropped. `claude plugin list`
+    // also emits `failed to load`, which the parser matches as neither enabled nor
+    // disabled: railway reports it (a hook clash) and its twelve skills still
+    // load. Treating anything unrecognised as disabled would have silently
+    // deleted those from the total, so anything not known-disabled still counts.
+    // Keyed on `<plugin>@<marketplace>`, not the bare name: the same plugin name
+    // can be installed from two marketplaces in different states, and a name-only
+    // set would drop the enabled copy along with the disabled one. `pluginName`
+    // is the cache directory, which is the marketplace.
+    //
+    // An identity enabled anywhere is treated as enabled. `claude plugin list`
+    // emits one row per scope, so the same identity legitimately appears twice —
+    // and counting a live plugin is the safe error to make, not dropping it.
+    const pluginIdentity = (plugin, marketplace) => `${plugin}@${marketplace}`;
+    const enabledIdentities = new Set(installed.filter((p) => p.enabled).map((p) => pluginIdentity(p.name, p.marketplace)));
+    const disabledIdentities = new Set(installed
+        .filter((p) => !p.enabled)
+        .map((p) => pluginIdentity(p.name, p.marketplace))
+        .filter((id) => !enabledIdentities.has(id)));
+    const isLoadedAtStartup = (s) => {
+        if (s.plugin === undefined || s.pluginName === undefined)
+            return true;
+        return !disabledIdentities.has(pluginIdentity(s.plugin, s.pluginName));
+    };
+    const activePluginSkills = pluginSkills.filter(isLoadedAtStartup);
+    const disabledPluginSkillTokens = sumListing(pluginSkills.filter((s) => !isLoadedAtStartup(s)));
+    const skillListingTokens = sumListing(localSkills) + sumListing(activePluginSkills);
     const agentListingTokens = sumListing(userSurfaces.agents);
     const commandListingTokens = sumListing(userSurfaces.commands);
     // Memory is per-project: a session loads ~/.claude/projects/<slug>/memory/
@@ -107,6 +140,15 @@ export async function scan(opts = {}) {
         commandListingTokens +
         claudeMdTokens +
         currentProjectMemoryTokens;
+    const currentProjectKnown = await pathExists(join(getProjectsDir(), currentProjectSlug));
+    // Only the skill-listing slice of a plugin's cost is recoverable startup
+    // context — see sumRecoverableStartupTokens. Aggregated by plugin name the
+    // same way `pluginCosts` is, so the two stay comparable.
+    const pluginSkillListingTokens = new Map();
+    for (const c of pluginCostBreakdowns) {
+        pluginSkillListingTokens.set(c.pluginName, (pluginSkillListingTokens.get(c.pluginName) ?? 0) + c.skillTokens);
+    }
+    const recoverableStartupTokens = sumRecoverableStartupTokens(issues, [...localSkills, ...pluginSkills], currentProjectSlug, pluginSkillListingTokens);
     return {
         localSkills,
         pluginSkills,
@@ -124,7 +166,107 @@ export async function scan(opts = {}) {
         userAgents: userSurfaces.agents,
         userCommands: userSurfaces.commands,
         currentProjectSlug,
+        currentProjectKnown,
         currentProjectMemoryTokens,
         allProjectsMemoryTokens,
+        recoverableStartupTokens,
+        disabledPluginSkillTokens,
     };
 }
+async function pathExists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Issue types whose cleanup moves a skill directory out of the listing. */
+const SKILL_MOVE_TYPES = new Set([
+    'template', 'duplicate', 'skill_dup', 'oversized_skill', 'unused_skill',
+    'backup_artifact',
+]);
+/**
+ * What acting on every issue would actually save at session start.
+ *
+ * Two corrections over a naive `sum(issues.tokens)`, both of which inflate:
+ *
+ * - **Per-path, not per-issue.** The detectors are independent, so one skill
+ *   routinely earns several findings at once (`duplicate` + `oversized_skill` +
+ *   `unused_skill`). Removing it once collects the saving once.
+ * - **Listing tokens, not body tokens.** `Issue.tokens` is the whole SKILL.md,
+ *   which is loaded only when the skill runs. Startup pays for the catalog
+ *   line alone. Conflating the two overstated savings ~80× in practice.
+ *
+ * Memory issues count only when they belong to the current project — the same
+ * per-project rule `totalTokensBefore` follows. Deletions that free disk but no
+ * context (`broken_symlink`, `temp_cache`) contribute nothing here by design.
+ *
+ * Three separate overlaps have to be collapsed, since every one of them inflates:
+ * the same skill path, the same plugin across cached versions, and a memory file
+ * that its own stale project already accounts for.
+ */
+export function sumRecoverableStartupTokens(issues, skills, currentProjectSlug, 
+/** Plugin name → its skill-listing tokens. See the `unused_plugin` branch. */
+pluginSkillListingTokens = new Map()) {
+    const listingByPath = new Map(skills.map((s) => [s.path, s.listingTokens]));
+    const countedPaths = new Set();
+    const countedPlugins = new Set();
+    let total = 0;
+    // `stale_project` names the slug alone; `oversized_memory` names
+    // `<slug>/<file>`. Match both without letting a sibling slug through — plain
+    // startsWith would count `-Users-me-app2` as part of `-Users-me-app`.
+    const isCurrentProject = (name) => name === currentProjectSlug || name.startsWith(currentProjectSlug + '/');
+    // Stale projects first: `stale_project.tokens` is the sum of every memory file
+    // in that project, so counting it settles the per-file findings inside it too.
+    // Charging both billed an oversized file twice and could claim more than the
+    // project's entire memory.
+    let currentProjectIsStale = false;
+    for (const issue of issues) {
+        if (issue.type !== 'stale_project' || !isCurrentProject(issue.name))
+            continue;
+        if (currentProjectIsStale)
+            continue;
+        currentProjectIsStale = true;
+        total += issue.tokens;
+    }
+    for (const issue of issues) {
+        if (SKILL_MOVE_TYPES.has(issue.type)) {
+            if (countedPaths.has(issue.path))
+                continue;
+            countedPaths.add(issue.path);
+            // A skill missing from the listing map costs nothing at startup.
+            total += listingByPath.get(issue.path) ?? 0;
+        }
+        else if (issue.type === 'unused_plugin') {
+            // Deliberately NOT `issue.tokens`. That is the plugin's full estimated
+            // cost from computePluginCosts — CLAUDE.md section + skills + MCP tools +
+            // commands — and two of those parts do not belong in a recovery figure
+            // presented against `totalTokensBefore`:
+            //   - the matched CLAUDE.md section is in the baseline but survives the
+            //     cleanup, since disabling a plugin does not edit the user's
+            //     CLAUDE.md (and this tool never modifies it at all);
+            //   - the MCP-tool and command estimates are genuinely freed, but are not
+            //     in the baseline, so counting them measures against a total that
+            //     never included them.
+            // The skill listings are the one component that is both. Deduped by name
+            // because the surface scan walks version directories, so a plugin with
+            // two cached versions raises two findings.
+            if (countedPlugins.has(issue.name))
+                continue;
+            countedPlugins.add(issue.name);
+            total += pluginSkillListingTokens.get(issue.name) ?? 0;
+        }
+        else if (issue.type === 'oversized_memory') {
+            // Another project's memory never loads here, so trimming it saves this
+            // session nothing.
+            if (!isCurrentProject(issue.name))
+                continue;
+            if (currentProjectIsStale)
+                continue; // already inside the stale-project total
+            total += issue.tokens;
+        }
+    }
+    return total;
+}

package/dist/scanner/plugin-skills.js

@@ -1,8 +1,46 @@
 import { join } from 'node:path';
 import { countTokensCached } from '../tokenizer.js';
 import { getPluginsDir } from '../paths.js';
-import { safeReadFile, safeReaddir, isDirectory, getDirSize } from './fs-walk.js';
+import { safeReadFile, safeReaddir, isDirectory, getDirSize, safeStat } from './fs-walk.js';
+import { pickActiveVersion } from './plugin-versions.js';
 import { listingTokensFromContent } from './skill-listing.js';
+async function resolveContentRoots(pluginBaseDir) {
+    const entries = await safeReaddir(pluginBaseDir);
+    // Flat layout: the cache entry holds content directly, with no plugin or
+    // version level (`<cache-entry>/skills/<skill>/`). Without this check the
+    // loop below reads `skills` as a plugin directory and each skill inside it as
+    // a candidate version, then picks exactly one — which is not a miscount but a
+    // silent disappearance: the whole entry reported zero skills.
+    if (entries.includes('skills'))
+        return [{ dir: pluginBaseDir }];
+    const roots = [];
+    for (const entry of entries) {
+        const pluginDir = join(pluginBaseDir, entry);
+        if (!(await isDirectory(pluginDir)))
+            continue;
+        const children = await safeReaddir(pluginDir);
+        if (children.includes('skills')) {
+            // Content root, not a version container.
+            roots.push({ dir: pluginDir, plugin: entry });
+            continue;
+        }
+        const versions = [];
+        for (const child of children) {
+            const versionDir = join(pluginDir, child);
+            if (!(await isDirectory(versionDir)))
+                continue;
+            const stats = await safeStat(versionDir);
+            versions.push({ version: child, installedAt: stats?.mtimeMs ?? 0, dir: versionDir });
+        }
+        const active = pickActiveVersion(versions);
+        // No subdirectories at all: hand back the plugin dir so the walk behaves
+        // exactly as it did before rather than silently dropping the plugin.
+        roots.push({ dir: active ? active.dir : pluginDir, plugin: entry });
+    }
+    // A marketplace with no plugin subdirectories still needs walking — some
+    // caches put content directly under the top level.
+    return roots.length > 0 ? roots : [{ dir: pluginBaseDir }];
+}
 export async function scanPluginSkills() {
     const skills = [];
     const plugins = [];
@@ -20,7 +58,11 @@ export async function scanPluginSkills() {
             return;
         }
         const pluginSkillNames = [];
-        const walkDir = async (dir) => {
+        const walkDir = async (dir, plugin) => {
+            // Kept generic: a plugin's content root is normally
+            // `<plugin>/<version>/`, but the walk also has to reach skills nested
+            // deeper. Version selection happens before we get here — see
+            // resolveContentRoots below — so this only ever descends one install.
             const entries = await safeReaddir(dir);
             for (const entry of entries) {
                 const entryPath = join(dir, entry);
@@ -44,16 +86,19 @@ export async function scanPluginSkills() {
                                 listingTokens: listingTokensFromContent(skillDir, content),
                                 source: 'plugin',
                                 pluginName,
+                                plugin,
                             });
                         }
                     }
                 }
                 else {
-                    await walkDir(entryPath);
+                    await walkDir(entryPath, plugin);
                 }
             }
         };
-        await walkDir(pluginDir);
+        for (const root of await resolveContentRoots(pluginDir)) {
+            await walkDir(root.dir, root.plugin);
+        }
         if (pluginSkillNames.length > 0) {
             plugins.push({
                 name: pluginName,

package/dist/scanner/plugin-surfaces.js

@@ -2,6 +2,7 @@ import { join } from 'node:path';
 import { statSync } from 'node:fs';
 import { readFileSync, readdirSync } from 'node:fs';
 import { getPluginsDir } from '../paths.js';
+import { pickActiveVersion } from './plugin-versions.js';
 import { listingTokensFromContent } from './skill-listing.js';
 import { SKILL_PROMPT_OVERHEAD_TOKENS } from './constants.js';
 function safeReaddir(p) {
@@ -108,13 +109,21 @@ export function scanPluginSurfaces() {
             const pluginBaseDir = join(marketplaceDir, pluginName);
             if (!isDir(pluginBaseDir))
                 continue;
-            // Each plugin may have version subdirectories
-            for (const version of safeReaddir(pluginBaseDir)) {
-                const installDir = join(pluginBaseDir, version);
-                if (!isDir(installDir))
-                    continue;
-                const dirStat = safeStat(installDir);
-                const installedAt = dirStat ? Number(dirStat.mtimeMs) : 0;
+            // A plugin may have several version subdirectories, but a session loads
+            // exactly one. Emitting a surface per version made every per-plugin cost
+            // a multiple of the truth, because computePluginCosts sums across
+            // surfaces while computePluginBreakdown picks a single one — the two
+            // disagreed, and the summed figure is what reached the user.
+            const versions = safeReaddir(pluginBaseDir)
+                .map((version) => ({ version, installDir: join(pluginBaseDir, version) }))
+                .filter((v) => isDir(v.installDir))
+                .map((v) => {
+                const dirStat = safeStat(v.installDir);
+                return { ...v, installedAt: dirStat ? Number(dirStat.mtimeMs) : 0 };
+            });
+            const active = pickActiveVersion(versions);
+            if (active) {
+                const { version, installDir, installedAt } = active;
                 const { names: skills, listingTokens: skillListingTokens } = scanSkills(installDir);
                 const mcpServerKeys = parseMcpServerKeys(installDir);
                 const mcpToolPrefixes = mcpServerKeys.map((key) => `plugin_${pluginName}_${key}`);

package/dist/scanner/plugin-versions.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Which cached version of a plugin a session actually loads.
+ *
+ * `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` can hold more than
+ * one version directory. `claude plugin update` leaves the old one behind as a
+ * symlink to the new one (`4.9.1 -> 4.15.4`), and `stat` follows it, so a naive
+ * walk sees two complete installs and counts every skill twice. Only one is ever
+ * loaded, so counting both inflated `totalTokensBefore` — the number the whole
+ * tool is built to report — by 14.5% on the machine where this was measured.
+ */
+export interface VersionedDir {
+    /** Directory name, normally a semver string. */
+    version: string;
+    /** Directory mtime in ms, the same signal plugin-surfaces calls `installedAt`. */
+    installedAt: number;
+}
+/**
+ * Compare two version directory names, newest last (sort-compatible).
+ *
+ * Numeric segment by segment, so `4.15.4` beats `4.9.1` — the lexicographic
+ * comparison that a plain string sort would do gets that backwards. Non-numeric
+ * segments fall back to string order, which keeps prereleases deterministic
+ * without pretending to implement full semver precedence.
+ */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * Pick the version a session would load, or null when there are none.
+ *
+ * Newest mtime wins, matching how `computePluginBreakdown` already chooses among
+ * surfaces. An update-symlink and its target report the *same* mtime — `stat`
+ * resolves the link — so the tie-break carries the real weight here: highest
+ * version. Without it the choice would depend on readdir order.
+ */
+export declare function pickActiveVersion<T extends VersionedDir>(candidates: T[]): T | null;

package/dist/scanner/plugin-versions.js

@@ -0,0 +1,53 @@
+/**
+ * Which cached version of a plugin a session actually loads.
+ *
+ * `~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/` can hold more than
+ * one version directory. `claude plugin update` leaves the old one behind as a
+ * symlink to the new one (`4.9.1 -> 4.15.4`), and `stat` follows it, so a naive
+ * walk sees two complete installs and counts every skill twice. Only one is ever
+ * loaded, so counting both inflated `totalTokensBefore` — the number the whole
+ * tool is built to report — by 14.5% on the machine where this was measured.
+ */
+/**
+ * Compare two version directory names, newest last (sort-compatible).
+ *
+ * Numeric segment by segment, so `4.15.4` beats `4.9.1` — the lexicographic
+ * comparison that a plain string sort would do gets that backwards. Non-numeric
+ * segments fall back to string order, which keeps prereleases deterministic
+ * without pretending to implement full semver precedence.
+ */
+export function compareVersions(a, b) {
+    const pa = a.split(/[.\-+]/);
+    const pb = b.split(/[.\-+]/);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const sa = pa[i] ?? '';
+        const sb = pb[i] ?? '';
+        const na = Number(sa);
+        const nb = Number(sb);
+        if (Number.isInteger(na) && Number.isInteger(nb) && sa !== '' && sb !== '') {
+            if (na !== nb)
+                return na - nb;
+        }
+        else if (sa !== sb) {
+            return sa < sb ? -1 : 1;
+        }
+    }
+    return 0;
+}
+/**
+ * Pick the version a session would load, or null when there are none.
+ *
+ * Newest mtime wins, matching how `computePluginBreakdown` already chooses among
+ * surfaces. An update-symlink and its target report the *same* mtime — `stat`
+ * resolves the link — so the tie-break carries the real weight here: highest
+ * version. Without it the choice would depend on readdir order.
+ */
+export function pickActiveVersion(candidates) {
+    if (candidates.length === 0)
+        return null;
+    return candidates.reduce((best, c) => {
+        if (c.installedAt !== best.installedAt)
+            return c.installedAt > best.installedAt ? c : best;
+        return compareVersions(c.version, best.version) > 0 ? c : best;
+    });
+}

package/dist/selection.d.ts

@@ -1,3 +1,16 @@
 import type { Issue } from './types.js';
+/**
+ * Parsed selection input, including whatever could not be understood.
+ *
+ * Unparseable fragments used to be dropped in silence. On a list that routinely
+ * runs to 70+ numbered items, the natural way to pick a span is `1-20` — and
+ * `parseInt('1-20')` is `1`, so the user asked for twenty items, got one, and
+ * was told nothing. Surfacing `invalid` lets the caller say what it ignored.
+ */
+export interface ParsedSelection {
+    indices: number[];
+    invalid: string[];
+}
+export declare function parseSelection(input: string, count: number): ParsedSelection;
 export declare function resolveSelection(input: string, issues: Issue[]): Issue[];
 export declare function resolveRestoreSelection(input: string, count: number): number[];

package/dist/selection.js

@@ -1,3 +1,42 @@
+/** Expand a `N` or `N-M` fragment into 1-based indices, or null if malformed. */
+function parseFragment(part, count) {
+    const range = /^(\d+)\s*-\s*(\d+)$/.exec(part);
+    if (range) {
+        const lo = parseInt(range[1], 10);
+        const hi = parseInt(range[2], 10);
+        if (lo < 1 || hi < 1 || lo > count || hi > count || lo > hi)
+            return null;
+        return Array.from({ length: hi - lo + 1 }, (_, k) => lo + k);
+    }
+    if (!/^\d+$/.test(part))
+        return null;
+    const num = parseInt(part, 10);
+    if (num < 1 || num > count)
+        return null;
+    return [num];
+}
+export function parseSelection(input, count) {
+    const indices = [];
+    const invalid = [];
+    const seen = new Set();
+    for (const raw of input.trim().toLowerCase().split(',')) {
+        const part = raw.trim();
+        if (part === '')
+            continue;
+        const nums = parseFragment(part, count);
+        if (nums === null) {
+            invalid.push(part);
+            continue;
+        }
+        for (const num of nums) {
+            if (seen.has(num))
+                continue;
+            seen.add(num);
+            indices.push(num);
+        }
+    }
+    return { indices, invalid };
+}
 export function resolveSelection(input, issues) {
     const trimmed = input.trim().toLowerCase();
     if (trimmed === 'none' || trimmed === 'n')
@@ -8,17 +47,7 @@ export function resolveSelection(input, issues) {
         // Default: tier 1 only
         return issues.filter((i) => i.tier === 1);
     }
-    // Parse comma-separated numbers → select exactly those items
-    const result = [];
-    const seen = new Set();
-    for (const part of trimmed.split(',')) {
-        const num = parseInt(part.trim(), 10);
-        if (!isNaN(num) && num >= 1 && num <= issues.length && !seen.has(num)) {
-            seen.add(num);
-            result.push(issues[num - 1]);
-        }
-    }
-    return result;
+    return parseSelection(trimmed, issues.length).indices.map((n) => issues[n - 1]);
 }
 export function resolveRestoreSelection(input, count) {
     const trimmed = input.trim().toLowerCase();
@@ -27,14 +56,6 @@ export function resolveRestoreSelection(input, count) {
     if (trimmed === 'all' || trimmed === 'a') {
         return Array.from({ length: count }, (_, i) => i);
     }
-    const indices = [];
-    const seen = new Set();
-    for (const part of trimmed.split(',')) {
-        const num = parseInt(part.trim(), 10);
-        if (!isNaN(num) && num >= 1 && num <= count && !seen.has(num)) {
-            seen.add(num);
-            indices.push(num - 1);
-        }
-    }
-    return indices;
+    // 0-based, unlike resolveSelection — restore indexes into the manifest array.
+    return parseSelection(trimmed, count).indices.map((n) => n - 1);
 }

package/dist/types.d.ts

@@ -14,7 +14,20 @@ export interface SkillInfo {
      */
     listingTokens: number;
     source: 'local' | 'plugin';
+    /**
+     * Cache directory this skill was found under — the *marketplace*, not the
+     * plugin. Kept as-is because `plugins[]` and the `disabled_plugin` detector
+     * match cache directories by this name (see parseDisabledPlugins).
+     */
     pluginName?: string;
+    /**
+     * The actual plugin, e.g. `oh-my-claudecode` where `pluginName` is `omc`.
+     *
+     * Needed because enabled/disabled state is reported per plugin, not per
+     * marketplace, and one marketplace can host both. Absent when the cache entry
+     * has no plugin level to read it from.
+     */
+    plugin?: string;
 }
 export interface BrokenSymlink {
     name: string;
@@ -81,10 +94,42 @@ export interface ScanResult {
     userCommands: UserSurfaceEntry[];
     /** Project slug (cwd with `/` → `-`) whose memory a session here would load. */
     currentProjectSlug: string;
+    /**
+     * Whether `~/.claude/projects/<currentProjectSlug>/` exists — i.e. whether
+     * Claude Code holds any state for this project.
+     *
+     * When false, `currentProjectMemoryTokens` is 0 because nothing is stored
+     * under this slug. That 0 is arithmetically correct either way; what the flag
+     * adds is *why*. A directory Claude has never opened genuinely has no memory,
+     * while a slug pointing somewhere the user did not mean — the plugin cache, a
+     * git worktree — produces the same 0 for a very different reason. Consumers
+     * of `--json` had no way to tell a scanned project from a mis-aimed one.
+     */
+    currentProjectKnown: boolean;
     /** Memory tokens actually loaded at startup — current project only. */
     currentProjectMemoryTokens: number;
     /** Memory tokens across every project on disk. Not a per-session cost. */
     allProjectsMemoryTokens: number;
+    /**
+     * Startup tokens that acting on every issue would actually recover.
+     *
+     * Deliberately NOT `sum(issues.tokens)`. Two things make that sum wrong:
+     *   1. Issues are per-finding, not per-path — one skill can be flagged
+     *      `duplicate` + `oversized_skill` + `unused_skill` and get counted 3×.
+     *   2. `Issue.tokens` is the full SKILL.md body, which is only paid when the
+     *      skill is invoked. Startup pays `listingTokens` — often ~80× smaller.
+     * Summing raw issue tokens on a real machine produced 215,535 "savings"
+     * against a 13,434-token startup total. This field is the honest number.
+     */
+    recoverableStartupTokens: number;
+    /**
+     * Skill-listing tokens belonging to plugins reported as disabled.
+     *
+     * Excluded from `totalTokensBefore` because a disabled plugin's skills are
+     * not in the session catalog. Reported separately so the number does not just
+     * vanish: it is what re-enabling everything would cost.
+     */
+    disabledPluginSkillTokens: number;
 }
 export interface ManifestEntry {
     date: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-slim",
-  "version": "2.12.1",
+  "version": "2.13.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

@@ -72,6 +72,24 @@ After getting the scan JSON, YOU must interpret and present results to the user.
 
 > **Templates below are shown in English for readability. Always translate headers, labels, and prompts into the user's detected language when rendering.**
 
+### 2-0. Two numbers that are not interchangeable
+
+The JSON reports token counts in two different units, and mixing them produces
+savings figures larger than the entire thing being saved:
+
+- **`listingTokens`** (and `totalTokensBefore`, `recoverableStartupTokens`) —
+  what a session pays at startup for the catalog line.
+- **`tokens`** on a skill or an issue — the whole SKILL.md body, paid only when
+  that skill is actually invoked.
+
+`Issue.tokens` is the second kind. **Never sum it and call the result savings.**
+On a real machine that sum was 215,535 against a 13,434-token startup total —
+16× the whole budget. Use `recoverableStartupTokens`, which the CLI already
+computes with duplicates collapsed and the right unit.
+
+Quote body tokens only when explaining what one skill costs *per invocation*,
+and label them that way.
+
 ### 2-1. Environment Snapshot Table
 
 Show a summary table:
@@ -82,7 +100,15 @@ Show a summary table:
 | Plugins | N (M skills) | ~X tok |
 | CLAUDE.md | XKB | X tok |
 | Memory files | N (XKB) | ~X tok |
-| **Session startup overhead** | | **~X tok** |
+| **Session startup overhead** | | **~X tok** (`totalTokensBefore`) |
+
+**Check `currentProjectKnown` before presenting memory numbers.** When it is
+`false`, Claude Code holds no state for that slug. The `0` is correct, but it
+may be answering the wrong question — the slug can point at a plugin cache or a
+git worktree rather than the project the user meant. Say that no project state
+backs this path and offer `--project-dir <path>`, instead of presenting the 0 as
+a clean result. Do not assert the memory was lost: a directory Claude has never
+opened really does have none.
 
 ### 2-2. Plugin Detail Table
 
@@ -123,7 +149,10 @@ End with a numbered action list, ordered by impact:
 2. What to consider
 3. What to leave alone and why
 
-Show estimated total token savings if all recommended actions are taken.
+For total savings, quote **`recoverableStartupTokens`** and state it against
+`totalTokensBefore` ("~2,700 of ~13,400 startup tokens"). Do not add up the
+per-issue numbers — see 2-0. A skill flagged three times is one cleanup, and
+its body size is not a startup cost.
 
 If subcommand is `scan`, stop here. Ask a localized equivalent of "Proceed with cleanup?" only for the full pipeline.