claude-slim 2.5.1 → 2.6.0

package/README.md

@@ -80,7 +80,7 @@ That's slower responses. Hitting your usage cap faster. Paying for context you'r
 | **Recommended** | Suggested | Duplicates, stale memory, disabled plugins, stale projects |
 | **Optional** | Your call | Oversized skills you might still use |
 
-**Clean** — Moves selected items to `~/.claude/skills.disabled/`. **Nothing is deleted. Ever.**
+**Clean** — Moves selected skills and project memory to `~/.claude/skills.disabled/`. Failed-install temp caches and dead symlink files are the only permanent cleanups, and they are labeled before selection.
 
 **Report** — Shows exactly what changed:
 
@@ -139,6 +139,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 doctor                   # Check scanner prerequisites and data fidelity
 /claude-slim restore                  # Bring back anything you disabled
 ```
 
@@ -150,6 +151,7 @@ npx claude-slim clean --dry-run          # See what would happen (no changes)
 npx claude-slim clean --auto             # Non-interactive, Tier 1 only (CI/scripts)
 npx claude-slim clean --lookback-days N  # Tune the unused-skill detection window
 npx claude-slim scan                     # Report only
+npx claude-slim doctor                   # Diagnose Node/Claude/session-log readiness
 npx claude-slim restore                  # Undo
 npx claude-slim report                   # Show savings from last clean
 ```
@@ -160,9 +162,9 @@ npx claude-slim report                   # Show savings from last clean
 
 | | |
 |---|---|
-| **Non-destructive** | Nothing is ever deleted. Disabled items move to `~/.claude/skills.disabled/` |
-| **Reversible** | `/claude-slim restore` brings anything back, any time |
-| **User-controlled** | Always asks before making changes. `--dry-run` to preview. |
+| **Non-destructive for user data** | Skills and project memory move to `~/.claude/skills.disabled/` |
+| **Reversible where state exists** | `/claude-slim restore` brings moved skills and project memory back |
+| **User-controlled** | Interactive runs ask before changes. `--dry-run` previews; `--auto` selects Tier 1 only. |
 | **Hands off** | Never touches CLAUDE.md, settings.json, or plugin configs |
 | **Scoped** | All operations are refused if the target path escapes `~/.claude/` |
 
@@ -174,7 +176,7 @@ npx claude-slim report                   # Show savings from last clean
 - **Git / project sources** — claude-slim only looks inside `~/.claude/`, never at your code.
 - **Anything outside `~/.claude/`** — a path-containment guard refuses destructive ops anywhere else, even if a tampered manifest asked it to.
 
-Only touched: entries under `~/.claude/skills/`, `~/.claude/plugins/cache/temp_local_*`, and `~/.claude/projects/*/memory/` — and even those are moved to `skills.disabled/`, not deleted (except `temp_local_*` failed-install caches, which are removed outright).
+Only touched: entries under `~/.claude/skills/`, `~/.claude/plugins/cache/temp_local_*`, and `~/.claude/projects/*/memory/`. Skill and memory entries are moved to `skills.disabled/`; broken symlink files are unlinked and `temp_local_*` failed-install caches are removed outright.
 
 ---
 

package/dist/cli.js

@@ -9,6 +9,7 @@ import { scan, SKILL_PROMPT_OVERHEAD_TOKENS } from './scanner.js';
 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 { resolveSelection, resolveRestoreSelection } from './selection.js';
 const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
 const { version: PKG_VERSION } = JSON.parse(readFileSync(pkgPath, 'utf-8'));
@@ -34,6 +35,23 @@ program
         console.log(formatScanSummary(result));
     }
 });
+// --- doctor ---
+program
+    .command('doctor')
+    .description('Check local Claude Code environment and scanner fidelity')
+    .option('--json', 'Output raw JSON')
+    .option('--lookback-days <n>', 'Days of session history for skill-usage analysis', '60')
+    .action(async (opts) => {
+    const report = await collectDoctorReport({
+        lookbackDays: parseInt(opts.lookbackDays, 10) || 60,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
+    else {
+        console.log(formatDoctorReport(report));
+    }
+});
 // --- clean ---
 program
     .command('clean')

package/dist/doctor.d.ts

@@ -0,0 +1,15 @@
+export type DoctorStatus = 'ok' | 'warn' | 'fail';
+export interface DoctorCheck {
+    label: string;
+    status: DoctorStatus;
+    detail: string;
+    hint?: string;
+}
+export interface DoctorReport {
+    checks: DoctorCheck[];
+}
+export declare function isSupportedRuntimeNode(version: string): boolean;
+export declare function collectDoctorReport(opts?: {
+    lookbackDays?: number;
+}): Promise<DoctorReport>;
+export declare function formatDoctorReport(report: DoctorReport): string;

package/dist/doctor.js

@@ -0,0 +1,119 @@
+import { access, readdir } from 'node:fs/promises';
+import { getClaudeDir, getPluginsDir, getProjectsDir, getSkillsDir } from './paths.js';
+import { runCommand } from './scanner/fs-walk.js';
+import { scanSessionUsage } from './scanner/sessions.js';
+const MIN_RUNTIME_NODE_MAJOR = 20;
+export function isSupportedRuntimeNode(version) {
+    const normalized = version.trim().replace(/^v/, '');
+    const major = Number.parseInt(normalized.split('.')[0] || '', 10);
+    return Number.isFinite(major) && major >= MIN_RUNTIME_NODE_MAJOR;
+}
+async function pathReadable(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function countEntries(path) {
+    try {
+        return (await readdir(path)).length;
+    }
+    catch {
+        return null;
+    }
+}
+export async function collectDoctorReport(opts = {}) {
+    const lookbackDays = opts.lookbackDays ?? 60;
+    const checks = [];
+    checks.push({
+        label: 'Node.js',
+        status: isSupportedRuntimeNode(process.version) ? 'ok' : 'fail',
+        detail: `${process.version} (requires >=${MIN_RUNTIME_NODE_MAJOR})`,
+        hint: isSupportedRuntimeNode(process.version)
+            ? undefined
+            : 'Install Node.js 20 or newer.',
+    });
+    const claudeDir = getClaudeDir();
+    const claudeDirReadable = await pathReadable(claudeDir);
+    checks.push({
+        label: 'Claude directory',
+        status: claudeDirReadable ? 'ok' : 'fail',
+        detail: claudeDir,
+        hint: claudeDirReadable ? undefined : 'Run Claude Code once so ~/.claude is created.',
+    });
+    const skillCount = await countEntries(getSkillsDir());
+    checks.push({
+        label: 'Local skills directory',
+        status: skillCount === null ? 'warn' : 'ok',
+        detail: skillCount === null ? `${getSkillsDir()} not readable` : `${skillCount} entries`,
+        hint: skillCount === null ? 'No local skills were found or the directory is not readable.' : undefined,
+    });
+    const pluginCount = await countEntries(getPluginsDir());
+    checks.push({
+        label: 'Plugin cache directory',
+        status: pluginCount === null ? 'warn' : 'ok',
+        detail: pluginCount === null ? `${getPluginsDir()} not readable` : `${pluginCount} entries`,
+        hint: pluginCount === null ? 'Install a Claude Code plugin if you expect plugin-skill scanning.' : undefined,
+    });
+    const pluginListOutput = await runCommand('claude', ['plugin', 'list']);
+    checks.push({
+        label: 'Claude plugin CLI',
+        status: pluginListOutput.trim() ? 'ok' : 'warn',
+        detail: pluginListOutput.trim() ? 'claude plugin list returned output' : 'no output from claude plugin list',
+        hint: pluginListOutput.trim()
+            ? undefined
+            : 'Install or sign in to Claude Code if disabled-plugin detection looks incomplete.',
+    });
+    const projectsReadable = await pathReadable(getProjectsDir());
+    if (!projectsReadable) {
+        checks.push({
+            label: 'Session transcripts',
+            status: 'warn',
+            detail: `${getProjectsDir()} not readable`,
+            hint: 'Unused-skill detection needs recent ~/.claude/projects/*.jsonl session logs.',
+        });
+    }
+    else {
+        const usage = await scanSessionUsage(lookbackDays);
+        checks.push({
+            label: 'Session transcripts',
+            status: usage.dataAvailable ? 'ok' : 'warn',
+            detail: `${usage.sessionsInWindow} sessions in last ${lookbackDays}d, ${usage.invokedSkills.size} invoked skills`,
+            hint: usage.dataAvailable
+                ? undefined
+                : 'Unused-skill detection will be suppressed until enough reliable session data exists.',
+        });
+    }
+    return { checks };
+}
+export function formatDoctorReport(report) {
+    const lines = ['', '\x1b[1m=== claude-slim doctor ===\x1b[0m', ''];
+    const symbols = {
+        ok: '\x1b[32m✓\x1b[0m',
+        warn: '\x1b[33m!\x1b[0m',
+        fail: '\x1b[31m✗\x1b[0m',
+    };
+    for (const check of report.checks) {
+        lines.push(`  ${symbols[check.status]} ${check.label}: ${check.detail}`);
+        if (check.hint && check.status !== 'ok') {
+            lines.push(`      ${check.hint}`);
+        }
+    }
+    const failed = report.checks.filter((c) => c.status === 'fail').length;
+    const warned = report.checks.filter((c) => c.status === 'warn').length;
+    lines.push('');
+    if (failed > 0) {
+        lines.push(`  ${failed} failing check(s), ${warned} warning(s).`);
+    }
+    else if (warned > 0) {
+        lines.push(`  No failing checks. ${warned} warning(s) may reduce scan fidelity.`);
+    }
+    else {
+        lines.push('  All checks passed.');
+    }
+    lines.push('');
+    return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-slim",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Analyze and reduce Claude Code token overhead",
   "type": "module",
   "bin": {

package/skills/claude-slim/SKILL.md

@@ -12,6 +12,7 @@ Analyze the user's Claude Code environment for token waste and perform non-destr
 - `/claude-slim` or `/claude-slim run` → full pipeline (scan → propose → execute → report)
 - `/claude-slim scan` → report only, no changes
 - `/claude-slim scan --json` → raw JSON output
+- `/claude-slim doctor` → check scanner prerequisites and session-log signal quality
 - `/claude-slim restore` → restore previously disabled items
 
 ---
@@ -131,6 +132,16 @@ When `/claude-slim restore` is invoked:
 cd "${CLAUDE_PLUGIN_ROOT}" && node dist/cli.js restore
 ```
 
+## Doctor
+
+When `/claude-slim doctor` is invoked:
+
+```bash
+cd "${CLAUDE_PLUGIN_ROOT}" && node 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.
+
 ---
 
 ## Language
@@ -139,7 +150,7 @@ Detect the user's language from their most recent message. Present all reports,
 
 ## Rules
 
-1. **Never delete.** The CLI moves items to `~/.claude/skills.disabled/`.
+1. **Never delete user data.** Skill directories and project memory are moved to `~/.claude/skills.disabled/`; dead symlink files and failed-install `temp_local_*` caches are permanent cleanups and should be described that way.
 2. **Never modify CLAUDE.md or settings.json.**
 3. **Never disable plugin-managed skills.** Report only.
 4. **Always confirm before executing.** Use `--dry-run` to preview changes.