claude-slim 2.11.0 → 2.12.1

package/README.md

@@ -165,6 +165,7 @@ npx claude-slim scan --no-codex          # Skip the ~/.codex scan
 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 update                   # Run the upgrade for this install method
 npx claude-slim restore                  # Undo
 npx claude-slim report                   # Show savings from last clean
 ```
@@ -247,16 +248,12 @@ Token counts come from [js-tiktoken](https://github.com/nicolo-ribaudo/js-tiktok
 
 ---
 
-## v2.11.0 — What's new
+## v2.12.1 — What's new
 
-Codex gets the same tiered propose-and-choose cleanup Claude Code has, minus the two categories Codex cannot honestly support.
+- **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.
 
-- **Codex cleanup, tiered.** Five of seven categories carry over because they are filesystem facts, not usage inferences: broken symlinks and unfilled templates (Tier 1), install leftovers in `~/.codex/.tmp` (Tier 1 — 146MB on the dev machine), backup copies and plugin-shadowed duplicates (Tier 2), oversized skills (Tier 3). Codex items join the same numbered list tagged `[codex]`. `--no-codex` opts out.
-- **`~/.codex/skills.disabled/`** — moves are reversible through the same `restore`, and manifest entries record which agent they came from.
-- **The path guard is now per-agent.** Not "inside any known root" — a Codex issue must not resolve into `~/.claude/` and vice versa, so a tampered manifest cannot cross between agents.
-- `unused_skill` and `oversized_memory` remain unavailable for Codex: no invocation record, and no `~/.codex/projects/*/memory/`.
-
-Tests: 347 → 374 (+27), the guard suite being the point — cross-agent isolation both directions, traversal escapes, and a `~/.claude-backup` sibling a naive `startsWith` would have allowed.
+Tests: 392 → 401 (+9).
 
 For older release notes, see [CHANGELOG.md](CHANGELOG.md).
 

package/dist/cli.js

@@ -10,7 +10,9 @@ 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 { 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';
@@ -39,10 +41,15 @@ program
     .description('Scan environment and report issues')
     .option('--json', 'Output raw JSON')
     .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)')
     .option('--no-codex', 'Skip the ~/.codex scan even if Codex is installed')
     .action(async (opts) => {
     await initTokenizer();
-    const result = await scan({ lookbackDays: parseNonNegativeInt(opts.lookbackDays, 60) });
+    const projectDir = resolveProjectDir(opts.projectDir);
+    const result = await scan({
+        lookbackDays: parseNonNegativeInt(opts.lookbackDays, 60),
+        projectDir,
+    });
     // Codex is scanned when present. Reported only — it is never modified, and
     // unused-skill detection is suppressed there for lack of a usage signal.
     // commander maps `--no-codex` to `opts.codex === false`, not `opts.noCodex`.
@@ -101,6 +108,81 @@ program
         console.log(`\n  \x1b[32m✓\x1b[0m claude-slim ${result.installed} is up to date.\n`);
     }
 });
+// --- update ---
+// Detection lives in `check-update`; this runs the command that detection
+// identified. claude-slim still never writes into a package manager's
+// directories itself — it invokes the manager, the same way cleanup already
+// invokes `claude plugin disable`.
+program
+    .command('update')
+    .description('Run the upgrade command for however this copy was installed')
+    .option('--yes', 'Skip the confirmation prompt')
+    .option('--dry-run', 'Show the commands without running them')
+    .action(async (opts) => {
+    const result = await checkForUpdate({ force: true });
+    const plan = planUpdate(result.installMethod);
+    console.log('');
+    console.log(`  Installed: ${result.installed}   Latest: ${result.latest ?? 'unknown'}`);
+    console.log(`  Install method: ${result.installMethod}`);
+    console.log('');
+    if (result.latest === null) {
+        console.log('  Could not reach the npm registry, so there is nothing to compare against.');
+        console.log('');
+        process.exitCode = 1;
+        return;
+    }
+    if (!result.outdated) {
+        console.log('  \x1b[32m✓\x1b[0m Already up to date.\n');
+        return;
+    }
+    if (!plan.runnable) {
+        console.log(`  ${plan.guidance}\n`);
+        return;
+    }
+    console.log('  Will run:');
+    for (const step of plan.steps)
+        console.log(`    ${renderStep(step)}`);
+    console.log('');
+    if (opts.dryRun) {
+        console.log('  \x1b[90mDry run — nothing was executed.\x1b[0m\n');
+        return;
+    }
+    const gate = confirmDecision(opts, Boolean(process.stdin.isTTY));
+    if (gate === 'refuse') {
+        console.error('  Refusing to run unattended. Re-run with --yes to confirm.\n');
+        process.exitCode = 1;
+        return;
+    }
+    if (gate === 'prompt') {
+        const answer = await askUser('  Proceed? [y/N] ');
+        if (!/^y(es)?$/i.test(answer)) {
+            console.log('  Cancelled.\n');
+            return;
+        }
+        console.log('');
+    }
+    const results = await runUpdate(plan);
+    for (const r of results) {
+        const mark = r.ok ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+        console.log(`  ${mark} ${renderStep(r.step)}`);
+        if (r.output)
+            console.log(r.output.split('\n').map((l) => `      ${l}`).join('\n'));
+    }
+    const failed = results.find((r) => !r.ok);
+    console.log('');
+    if (failed) {
+        console.log('  Update did not complete. Run the commands above manually to see the full error.\n');
+        process.exitCode = 1;
+    }
+    else if (result.installMethod === 'plugin') {
+        // The new version is on disk but the running session still holds the old
+        // one — without saying so, users update, re-run, and see identical output.
+        console.log('  \x1b[33m!\x1b[0m Restart Claude Code for the update to take effect.\n');
+    }
+    else {
+        console.log('  \x1b[32m✓\x1b[0m Updated.\n');
+    }
+});
 // --- clean ---
 program
     .command('clean')
@@ -109,6 +191,7 @@ program
     .option('--auto', 'Non-interactive: auto-select Tier 1 items only')
     .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)')
     .option('--no-codex', 'Skip ~/.codex entirely')
     .action(async (opts) => {
     await runCleanPipeline({
@@ -117,6 +200,7 @@ program
         sessionsPerDay: parseNonNegativeInt(opts.sessionsPerDay, 2),
         lookbackDays: parseNonNegativeInt(opts.lookbackDays, 60),
         codex: opts.codex !== false,
+        projectDir: opts.projectDir,
     });
 });
 // --- restore ---
@@ -274,10 +358,28 @@ program.action(async () => {
     }
     await runCleanPipeline({ dryRun: false, auto: false, sessionsPerDay: 2, lookbackDays: 60, codex: true });
 });
+/**
+ * Resolve which directory's project memory counts toward the startup estimate.
+ *
+ * Warns when the CLI is running from its own install directory and no explicit
+ * 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.
+ */
+function resolveProjectDir(explicit) {
+    if (explicit)
+        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' +
+            '    (or run from your project) for an accurate startup total.\n');
+    }
+    return undefined;
+}
 // --- shared clean pipeline ---
 async function runCleanPipeline(opts) {
     await initTokenizer();
-    const result = await scan({ lookbackDays: opts.lookbackDays });
+    const result = await scan({ lookbackDays: opts.lookbackDays, projectDir: resolveProjectDir(opts.projectDir) });
     // Codex issues join the same tiered list. They carry `agent: 'codex'`, which
     // is what keeps the cleaner's path guard pointed at ~/.codex/.
     const codexContents = new Map();

package/dist/paths.d.ts

@@ -12,6 +12,17 @@ export declare function getDisabledDir(): string;
  * the startup estimate must not sum memory across every project on disk.
  */
 export declare function getCurrentProjectSlug(cwd?: string): string;
+/**
+ * True when `cwd` sits inside claude-slim's own install rather than a project.
+ *
+ * The `/claude-slim` skill invokes the CLI with `cd "${CLAUDE_PLUGIN_ROOT}"`,
+ * which makes `process.cwd()` the plugin cache directory. The project slug then
+ * resolves to that path, no memory matches it, and the startup estimate silently
+ * drops every project-memory token — 108,570 of them on the machine where this
+ * was found. Detecting it lets the caller fail loudly or be told to pass
+ * `--project-dir` instead of quietly reporting zero.
+ */
+export declare function looksLikeToolInstallDir(cwd?: string): boolean;
 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

@@ -26,6 +26,22 @@ export function getDisabledDir() {
 export function getCurrentProjectSlug(cwd = process.cwd()) {
     return resolve(cwd).replace(/\//g, '-');
 }
+/**
+ * True when `cwd` sits inside claude-slim's own install rather than a project.
+ *
+ * The `/claude-slim` skill invokes the CLI with `cd "${CLAUDE_PLUGIN_ROOT}"`,
+ * which makes `process.cwd()` the plugin cache directory. The project slug then
+ * resolves to that path, no memory matches it, and the startup estimate silently
+ * drops every project-memory token — 108,570 of them on the machine where this
+ * was found. Detecting it lets the caller fail loudly or be told to pass
+ * `--project-dir` instead of quietly reporting zero.
+ */
+export function looksLikeToolInstallDir(cwd = process.cwd()) {
+    const p = resolve(cwd).replace(/\\/g, '/');
+    return (p.includes('/.claude/plugins/') ||
+        p.includes('/_npx/') ||
+        /\/node_modules\/claude-slim(\/|$)/.test(p));
+}
 export function getManifestPath() {
     return join(getDisabledDir(), 'manifest.json');
 }

package/dist/scanner/index.d.ts

@@ -1,5 +1,14 @@
 import type { ScanResult } from '../types.js';
 export interface ScanOptions {
     lookbackDays?: number;
+    /**
+     * Directory whose project memory counts toward the startup estimate.
+     *
+     * Defaults to `process.cwd()`, which is wrong whenever the CLI is launched
+     * from its own install directory — the `/claude-slim` skill does exactly that
+     * via `cd "${CLAUDE_PLUGIN_ROOT}"`, and every project-memory token silently
+     * dropped out of the total as a result.
+     */
+    projectDir?: string;
 }
 export declare function scan(opts?: ScanOptions): Promise<ScanResult>;

package/dist/scanner/index.js

@@ -97,7 +97,7 @@ export async function scan(opts = {}) {
     // disk. Summing all of them (pre-2.8 behaviour) inflated the startup estimate
     // by a factor of however many projects the user had — 100k+ tokens on a busy
     // machine, for a number labelled "tokens at session start".
-    const currentProjectSlug = getCurrentProjectSlug();
+    const currentProjectSlug = getCurrentProjectSlug(opts.projectDir);
     const currentProjectMemoryTokens = memoryFiles
         .filter((m) => m.project === currentProjectSlug)
         .reduce((sum, m) => sum + m.tokens, 0);

package/dist/update-run.d.ts

@@ -0,0 +1,40 @@
+import type { InstallMethod } from './update-check.js';
+export interface UpdateStep {
+    file: string;
+    args: string[];
+}
+export interface UpdatePlan {
+    /** false when there is nothing to execute — see `guidance`. */
+    runnable: boolean;
+    steps: UpdateStep[];
+    /** Why nothing runs, for the methods where that is the correct answer. */
+    guidance?: string;
+}
+export declare function planUpdate(method: InstallMethod): UpdatePlan;
+/** Human-readable rendering of a step, matching what the user would type. */
+export declare function renderStep(step: UpdateStep): string;
+export interface StepResult {
+    step: UpdateStep;
+    ok: boolean;
+    output: string;
+}
+/**
+ * Run the plan's steps in order, stopping at the first failure.
+ *
+ * Sequential rather than parallel, and halting on error, because step 2 depends
+ * on step 1 having refreshed the marketplace — running it against a stale
+ * manifest would report success while changing nothing.
+ */
+export declare function runUpdate(plan: UpdatePlan): Promise<StepResult[]>;
+export type ConfirmDecision = 'run' | 'prompt' | 'refuse';
+/**
+ * Decide how to gate an update that will modify the user's install.
+ *
+ * Refusing when there is no TTY is the important case: piped into a script or a
+ * CI job, there is nobody to answer the prompt, and silently proceeding would
+ * mean a tool that changes an installation without anyone agreeing to it.
+ * `--yes` is how you say so deliberately.
+ */
+export declare function confirmDecision(opts: {
+    yes?: boolean;
+}, isTTY: boolean): ConfirmDecision;

package/dist/update-run.js

@@ -0,0 +1,101 @@
+import { execFile } from 'node:child_process';
+// Running the upgrade.
+//
+// v2.9.0 shipped detection only, on the reasoning that updating is the package
+// manager's job. Half of that was right and half was not. Writing into the
+// plugin directory ourselves would indeed corrupt an install — but *invoking*
+// the package manager is something this tool already does elsewhere
+// (`claude plugin disable` during unused-plugin cleanup). Refusing to invoke it
+// here was inconsistent, not principled.
+//
+// So: still never write to those directories directly. Just run the command the
+// user would have typed, after showing it to them.
+//
+// Every argv below is a fixed literal. Nothing from the environment, the
+// manifest, or user input is interpolated, and execFile never routes through a
+// shell — so there is no argument-injection surface to guard.
+const STEP_TIMEOUT_MS = 180_000;
+export function planUpdate(method) {
+    switch (method) {
+        case 'plugin':
+            return {
+                runnable: true,
+                steps: [
+                    // Refresh the marketplace first; otherwise `plugin update` compares
+                    // against a stale manifest and reports "already up to date".
+                    { file: 'claude', args: ['plugin', 'marketplace', 'update', 'claude-slim'] },
+                    // The qualified id is required: the bare name fails with
+                    // `Plugin "claude-slim" not found` when a marketplace shares its name.
+                    { file: 'claude', args: ['plugin', 'update', 'claude-slim@claude-slim'] },
+                ],
+            };
+        case 'global':
+            return {
+                runnable: true,
+                steps: [{ file: 'npm', args: ['install', '-g', 'claude-slim@latest'] }],
+            };
+        case 'npx':
+            return {
+                runnable: false,
+                steps: [],
+                guidance: 'npx resolves the latest version on every invocation, so there is nothing to update. ' +
+                    'If a stale copy is cached, run `npx claude-slim@latest` once to refresh it.',
+            };
+        case 'source':
+            return {
+                runnable: false,
+                steps: [],
+                guidance: 'This is a source checkout. Updating it means pulling your own repository, ' +
+                    'which claude-slim will not do on your behalf — run `git pull && npm install` yourself.',
+            };
+        default:
+            return {
+                runnable: false,
+                steps: [],
+                guidance: 'Could not tell how this copy was installed, so no upgrade command can be chosen safely. ' +
+                    'Update it the same way you installed it.',
+            };
+    }
+}
+/** Human-readable rendering of a step, matching what the user would type. */
+export function renderStep(step) {
+    return [step.file, ...step.args].join(' ');
+}
+function runStep(step) {
+    return new Promise((resolve) => {
+        execFile(step.file, step.args, { timeout: STEP_TIMEOUT_MS }, (err, stdout, stderr) => {
+            const output = [stdout, stderr].map((s) => s?.trim()).filter(Boolean).join('\n');
+            resolve({ step, ok: !err, output: err ? `${err.message}${output ? `\n${output}` : ''}` : output });
+        });
+    });
+}
+/**
+ * Run the plan's steps in order, stopping at the first failure.
+ *
+ * Sequential rather than parallel, and halting on error, because step 2 depends
+ * on step 1 having refreshed the marketplace — running it against a stale
+ * manifest would report success while changing nothing.
+ */
+export async function runUpdate(plan) {
+    const results = [];
+    for (const step of plan.steps) {
+        const result = await runStep(step);
+        results.push(result);
+        if (!result.ok)
+            break;
+    }
+    return results;
+}
+/**
+ * Decide how to gate an update that will modify the user's install.
+ *
+ * Refusing when there is no TTY is the important case: piped into a script or a
+ * CI job, there is nobody to answer the prompt, and silently proceeding would
+ * mean a tool that changes an installation without anyone agreeing to it.
+ * `--yes` is how you say so deliberately.
+ */
+export function confirmDecision(opts, isTTY) {
+    if (opts.yes)
+        return 'run';
+    return isTTY ? 'prompt' : 'refuse';
+}

package/package.json

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

@@ -23,7 +23,7 @@ Analyze the user's Claude Code environment for token waste and perform non-destr
 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
+node "${CLAUDE_PLUGIN_ROOT}/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.
@@ -50,13 +50,13 @@ If `"outdated": false`, say nothing and continue to Phase 1.
 Run the CLI to collect environment data:
 
 ```bash
-cd "${CLAUDE_PLUGIN_ROOT}" && node dist/cli.js scan --json
+node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js" scan --json
 ```
 
 If `CLAUDE_PLUGIN_ROOT` is not set:
 ```bash
 PLUGIN_DIR=$(find ~/.claude/plugins -path "*/claude-slim/dist/cli.js" -type f 2>/dev/null | head -1 | xargs dirname | xargs dirname)
-cd "$PLUGIN_DIR" && node dist/cli.js scan --json
+node "$PLUGIN_DIR/dist/cli.js" scan --json
 ```
 
 If `node` is not available, fall back to the legacy bash scanner:
@@ -134,18 +134,18 @@ If subcommand is `scan`, stop here. Ask a localized equivalent of "Proceed with
 Run the interactive clean command:
 
 ```bash
-cd "${CLAUDE_PLUGIN_ROOT}" && node dist/cli.js clean
+node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js" clean
 ```
 
 Or with dry-run:
 ```bash
-cd "${CLAUDE_PLUGIN_ROOT}" && node dist/cli.js clean --dry-run
+node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js" clean --dry-run
 ```
 
 After cleanup, re-run scan to get updated numbers, then show the savings report:
 
 ```bash
-cd "${CLAUDE_PLUGIN_ROOT}" && node dist/cli.js report
+node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js" report
 ```
 
 Present the report box AND the before/after breakdown table to the user.
@@ -157,7 +157,7 @@ Present the report box AND the before/after breakdown table to the user.
 When `/claude-slim restore` is invoked:
 
 ```bash
-cd "${CLAUDE_PLUGIN_ROOT}" && node dist/cli.js restore
+node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js" restore
 ```
 
 ## Doctor
@@ -165,7 +165,7 @@ cd "${CLAUDE_PLUGIN_ROOT}" && node dist/cli.js restore
 When `/claude-slim doctor` is invoked:
 
 ```bash
-cd "${CLAUDE_PLUGIN_ROOT}" && node dist/cli.js doctor
+node "${CLAUDE_PLUGIN_ROOT}/dist/cli.js" doctor
 ```
 
 Explain warnings in the user's language. Pay special attention to session-log warnings because they explain why unused-skill detection may be suppressed.