claude-slim 2.3.0 → 2.5.0

package/README.md

@@ -20,18 +20,11 @@ Every Claude Code session auto-loads every skill, memory file, and plugin instru
 
 ---
 
-### The problem, visualized
+### See it in action
 
-```
-  Session start token budget
-  ┌──────────────────────────────────────────────────┐
-  │██████████████████████████░░░░░░░░░░░░░░░░░░░░░░░░│ Before claude-slim
-  │ 12K tokens consumed ↑    your actual work ↑      │
-  ├──────────────────────────────────────────────────┤
-  │██████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │ After claude-slim
-  │ 5K ↑            more room for your work ↑        │
-  └──────────────────────────────────────────────────┘
-```
+<p align="center">
+  <img src="docs/demo.gif" alt="claude-slim cleanup: 11,442 tokens of overhead reduced to ~5,800 in 45 seconds" width="900" />
+</p>
 
 Where the bloat hides:
 
@@ -73,6 +66,7 @@ That's slower responses. Hitting your usage cap faster. Paying for context you'r
 | Duplicates | Same skill registered from multiple sources |
 | Empty templates | Placeholder skills with no content |
 | Oversized files | SKILL.md over 10KB |
+| **Unused skills** | **Local skills never invoked in your last N days of sessions (default 60d)** |
 | Stale memory | Large memory files loaded every session |
 | Disabled plugins | Installed but disabled plugins still in cache |
 | Stale projects | Project memory untouched for 90+ days |
@@ -141,21 +135,23 @@ Then just type `/claude-slim` in any session.
 ## Usage
 
 ```bash
-/claude-slim              # Full pipeline: scan → propose → clean → report
-/claude-slim scan         # Report only, no changes
-/claude-slim scan --json  # Machine-readable JSON output
-/claude-slim restore      # Bring back anything you disabled
+/claude-slim                          # Full pipeline: scan → propose → clean → report
+/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 restore                  # Bring back anything you disabled
 ```
 
 CLI equivalents:
 
 ```bash
-npx claude-slim clean             # Full pipeline
-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 scan              # Report only
-npx claude-slim restore           # Undo
-npx claude-slim report            # Show savings from last clean
+npx claude-slim clean                    # Full pipeline
+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 restore                  # Undo
+npx claude-slim report                   # Show savings from last clean
 ```
 
 ---
@@ -212,6 +208,20 @@ From a real cleanup session:
 
 ---
 
+## 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.
@@ -242,7 +252,7 @@ From a real cleanup session:
 
 ## Requirements
 
-- Node.js 18+
+- Node.js 20+
 - macOS or Linux
 - Claude Code CLI
 

package/dist/cleaner.js

@@ -51,7 +51,8 @@ export async function cleanIssues(issues) {
             else if (issue.type === 'template' ||
                 issue.type === 'duplicate' ||
                 issue.type === 'skill_dup' ||
-                issue.type === 'oversized_skill') {
+                issue.type === 'oversized_skill' ||
+                issue.type === 'unused_skill') {
                 // Move skill directory to disabled — use name (not basename) to avoid namespace collisions
                 const safeName = issue.name.replace(/\//g, '--');
                 const dest = join(disabledDir, safeName);

package/dist/cli.js

@@ -22,9 +22,10 @@ program
     .command('scan')
     .description('Scan environment and report issues')
     .option('--json', 'Output raw JSON')
+    .option('--lookback-days <n>', 'Days of session history for skill-usage analysis', '60')
     .action(async (opts) => {
     await initTokenizer();
-    const result = await scan();
+    const result = await scan({ lookbackDays: parseInt(opts.lookbackDays, 10) || 60 });
     await flushCache();
     if (opts.json) {
         console.log(JSON.stringify(result, null, 2));
@@ -40,11 +41,13 @@ program
     .option('--dry-run', 'Show what would happen without making changes')
     .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')
     .action(async (opts) => {
     await runCleanPipeline({
         dryRun: !!opts.dryRun,
         auto: !!opts.auto,
         sessionsPerDay: parseInt(opts.sessionsPerDay, 10) || 2,
+        lookbackDays: parseInt(opts.lookbackDays, 10) || 60,
     });
 });
 // --- restore ---
@@ -110,9 +113,10 @@ program
     .command('report')
     .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')
     .action(async (opts) => {
     await initTokenizer();
-    const result = await scan();
+    const result = await scan({ lookbackDays: parseInt(opts.lookbackDays, 10) || 60 });
     const entries = await readManifest();
     const movedEntries = entries.filter((e) => e.tokenCount && e.tokenCount > 0);
     if (movedEntries.length === 0) {
@@ -125,7 +129,9 @@ program
     // Only skill-type entries contributed to the per-skill prompt overhead
     // (stale_project restores memory tokens separately; broken_symlink/
     // temp_cache never counted toward totalTokensBefore).
-    const SKILL_TYPES = new Set(['template', 'duplicate', 'skill_dup', 'oversized_skill']);
+    const SKILL_TYPES = new Set([
+        'template', 'duplicate', 'skill_dup', 'oversized_skill', 'unused_skill',
+    ]);
     const removedSkillEntries = movedEntries.filter((e) => SKILL_TYPES.has(e.type));
     const removedMemoryTokens = movedEntries
         .filter((e) => e.type === 'stale_project')
@@ -155,12 +161,12 @@ program
 });
 // --- default (no subcommand) → run clean ---
 program.action(async () => {
-    await runCleanPipeline({ dryRun: false, auto: false, sessionsPerDay: 2 });
+    await runCleanPipeline({ dryRun: false, auto: false, sessionsPerDay: 2, lookbackDays: 60 });
 });
 // --- shared clean pipeline ---
 async function runCleanPipeline(opts) {
     await initTokenizer();
-    const result = await scan();
+    const result = await scan({ lookbackDays: opts.lookbackDays });
     if (result.issues.length === 0) {
         console.log('\n  \x1b[32mAlready slim!\x1b[0m No issues found.\n');
         await flushCache();
@@ -207,7 +213,7 @@ async function runCleanPipeline(opts) {
     console.log('');
     const cleanResult = await cleanIssues(selectedIssues);
     // Re-scan after cleanup for accurate breakdown
-    const afterResult = await scan();
+    const afterResult = await scan({ lookbackDays: opts.lookbackDays });
     const reportData = calculateReport(result, afterResult, cleanResult.moved, opts.sessionsPerDay);
     console.log('');
     console.log(formatReportBox(reportData));

package/dist/scanner/detectors.d.ts

@@ -11,6 +11,9 @@ export interface DetectorContext {
     disabledPlugins: Set<string>;
     plugins: PluginInfo[];
     contents: Map<string, string>;
+    recentSkillInvocations: Set<string>;
+    sessionDataAvailable: boolean;
+    lookbackDays: number;
 }
 export interface Detector {
     name: string;

package/dist/scanner/detectors.js

@@ -144,6 +144,37 @@ const staleProjectDetector = {
         });
     },
 };
+const unusedSkillDetector = {
+    name: 'unused_skill',
+    detect({ localSkills, recentSkillInvocations, sessionDataAvailable, lookbackDays, }) {
+        // Suppress entirely when the data source is unreliable — better no signal
+        // than a wrong one that flags every skill as unused.
+        if (!sessionDataAvailable)
+            return [];
+        const issues = [];
+        for (const skill of localSkills) {
+            // Direct hit: invocation set contains the skill name as-is.
+            if (recentSkillInvocations.has(skill.name))
+                continue;
+            // Nested skill (e.g. "org/ship"): also check the bare leaf name, which
+            // is how it would appear in a Skill tool_use input.
+            if (skill.name.includes('/')) {
+                const leaf = skill.name.split('/').pop();
+                if (recentSkillInvocations.has(leaf))
+                    continue;
+            }
+            issues.push({
+                type: 'unused_skill',
+                tier: 3,
+                name: skill.name,
+                detail: `not invoked in ${lookbackDays}d`,
+                tokens: skill.tokens,
+                path: skill.path,
+            });
+        }
+        return issues;
+    },
+};
 const disabledPluginDetector = {
     name: 'disabled_plugin',
     detect({ plugins, disabledPlugins }) {
@@ -174,6 +205,7 @@ export const detectors = [
     tempCacheDetector,
     oversizedMemoryDetector,
     staleProjectDetector,
+    unusedSkillDetector,
     disabledPluginDetector,
 ];
 export function classifyIssues(ctx, registry = detectors) {

package/dist/scanner/index.d.ts

@@ -1,2 +1,5 @@
 import type { ScanResult } from '../types.js';
-export declare function scan(): Promise<ScanResult>;
+export interface ScanOptions {
+    lookbackDays?: number;
+}
+export declare function scan(opts?: ScanOptions): Promise<ScanResult>;

package/dist/scanner/index.js

@@ -8,15 +8,19 @@ import { scanMemoryFiles } from './memory.js';
 import { scanMcpServers } from './mcp.js';
 import { parseClaudeMdSections } from './claude-md.js';
 import { getDisabledPlugins } from './disabled-plugins.js';
+import { scanSessionUsage } from './sessions.js';
 import { classifyIssues } from './detectors.js';
 import { SKILL_PROMPT_OVERHEAD_TOKENS } from './constants.js';
-export async function scan() {
-    const [{ skills: localSkills, brokenSymlinks, contents }, { skills: pluginSkills, plugins, tempCaches }, { memoryFiles, staleProjects }, mcp, disabledPlugins,] = await Promise.all([
+const DEFAULT_LOOKBACK_DAYS = 60;
+export async function scan(opts = {}) {
+    const lookbackDays = opts.lookbackDays ?? DEFAULT_LOOKBACK_DAYS;
+    const [{ skills: localSkills, brokenSymlinks, contents }, { skills: pluginSkills, plugins, tempCaches }, { memoryFiles, staleProjects }, mcp, disabledPlugins, sessionUsage,] = await Promise.all([
         scanLocalSkills(),
         scanPluginSkills(),
         scanMemoryFiles(),
         scanMcpServers(),
         getDisabledPlugins(),
+        scanSessionUsage(lookbackDays),
     ]);
     // Annotate plugin status
     for (const plugin of plugins) {
@@ -33,6 +37,9 @@ export async function scan() {
         localSkills, pluginSkills, brokenSymlinks, memoryFiles,
         tempCaches, staleProjects, disabledPlugins, plugins,
         contents,
+        recentSkillInvocations: sessionUsage.invokedSkills,
+        sessionDataAvailable: sessionUsage.dataAvailable,
+        lookbackDays,
     });
     // Estimate total tokens at startup
     const skillListingTokens = (localSkills.length + pluginSkills.length) * SKILL_PROMPT_OVERHEAD_TOKENS;

package/dist/scanner/sessions.d.ts

@@ -0,0 +1,8 @@
+export interface SessionScanResult {
+    invokedSkills: Set<string>;
+    dataAvailable: boolean;
+    sessionsScanned: number;
+    sessionsInWindow: number;
+}
+export declare function extractSkillsFromTranscript(content: string): string[];
+export declare function scanSessionUsage(lookbackDays: number): Promise<SessionScanResult>;

package/dist/scanner/sessions.js

@@ -0,0 +1,150 @@
+import { readFile, readdir, stat, writeFile, mkdir, rename } from 'node:fs/promises';
+import { join, dirname } from 'node:path';
+import { getClaudeDir } from '../paths.js';
+const CACHE_VERSION = 1;
+// Below this many sessions in the lookback window we suppress unused-skill
+// classification — too little signal, "unused" would be misleading.
+const MIN_SESSIONS_FOR_DATA_AVAILABLE = 3;
+function getCachePath() {
+    return join(getClaudeDir(), '.skill-usage-cache.json');
+}
+async function loadCache() {
+    try {
+        const raw = await readFile(getCachePath(), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (parsed.version !== CACHE_VERSION)
+            return { version: CACHE_VERSION, entries: {} };
+        return parsed;
+    }
+    catch {
+        return { version: CACHE_VERSION, entries: {} };
+    }
+}
+async function saveCache(cache) {
+    const target = getCachePath();
+    const tmp = target + '.tmp';
+    try {
+        await mkdir(dirname(target), { recursive: true });
+        // Atomic write — same pattern as token cache. A crash mid-flush leaves the
+        // prior cache intact rather than a torn JSON file.
+        await writeFile(tmp, JSON.stringify(cache));
+        await rename(tmp, target);
+    }
+    catch {
+        // Non-critical: missing cache just means a slower next scan.
+    }
+}
+// Extract Skill-tool invocations from a single JSONL session log.
+// Each line in `~/.claude/projects/<slug>/<sessionId>.jsonl` is a JSON event;
+// we look for `message.content[]` entries shaped
+//   { type: 'tool_use', name: 'Skill', input: { skill: '<id>' } }
+// and collect the `skill` strings (e.g. 'superpowers:brainstorming').
+//
+// Schema-defensive: any line/field that does not match is silently skipped,
+// so a partial schema change degrades gracefully rather than throwing.
+export function extractSkillsFromTranscript(content) {
+    const skills = [];
+    const lines = content.split('\n');
+    for (const line of lines) {
+        if (!line)
+            continue;
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (typeof obj !== 'object' || obj === null)
+            continue;
+        const message = obj.message;
+        if (typeof message !== 'object' || message === null)
+            continue;
+        const msgContent = message.content;
+        if (!Array.isArray(msgContent))
+            continue;
+        for (const c of msgContent) {
+            if (typeof c !== 'object' || c === null)
+                continue;
+            const rec = c;
+            if (rec.type !== 'tool_use' || rec.name !== 'Skill')
+                continue;
+            const input = rec.input;
+            if (typeof input !== 'object' || input === null)
+                continue;
+            const skill = input.skill;
+            if (typeof skill === 'string')
+                skills.push(skill);
+        }
+    }
+    return skills;
+}
+// Walk every `~/.claude/projects/<slug>/*.jsonl` whose mtime falls inside the
+// lookback window. Per-file results are cached by mtime, so warm scans only
+// re-read files that have changed.
+export async function scanSessionUsage(lookbackDays) {
+    const projectsDir = join(getClaudeDir(), 'projects');
+    const cutoffMs = Date.now() - lookbackDays * 24 * 60 * 60 * 1000;
+    const cache = await loadCache();
+    // Pruned cache: only entries seen this scan survive. Keeps the file bounded
+    // across many scans even as old session logs get rotated/deleted.
+    const newEntries = {};
+    const invokedSkills = new Set();
+    let sessionsScanned = 0;
+    let sessionsInWindow = 0;
+    let projectDirs = [];
+    try {
+        projectDirs = await readdir(projectsDir);
+    }
+    catch {
+        return { invokedSkills, dataAvailable: false, sessionsScanned: 0, sessionsInWindow: 0 };
+    }
+    for (const projectName of projectDirs) {
+        const projectPath = join(projectsDir, projectName);
+        let entries = [];
+        try {
+            entries = await readdir(projectPath);
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.endsWith('.jsonl'))
+                continue;
+            const filePath = join(projectPath, entry);
+            let mtimeMs;
+            try {
+                mtimeMs = (await stat(filePath)).mtimeMs;
+            }
+            catch {
+                continue;
+            }
+            sessionsScanned++;
+            if (mtimeMs < cutoffMs)
+                continue;
+            sessionsInWindow++;
+            // Cache hit: reuse the parsed skill list, no I/O on the file body.
+            const cached = cache.entries[filePath];
+            if (cached && cached.mtimeMs === mtimeMs) {
+                for (const s of cached.skills)
+                    invokedSkills.add(s);
+                newEntries[filePath] = cached;
+                continue;
+            }
+            let content;
+            try {
+                content = await readFile(filePath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            const skills = extractSkillsFromTranscript(content);
+            for (const s of skills)
+                invokedSkills.add(s);
+            newEntries[filePath] = { mtimeMs, skills: Array.from(new Set(skills)) };
+        }
+    }
+    const dataAvailable = sessionsInWindow >= MIN_SESSIONS_FOR_DATA_AVAILABLE && invokedSkills.size > 0;
+    await saveCache({ version: CACHE_VERSION, entries: newEntries });
+    return { invokedSkills, dataAvailable, sessionsScanned, sessionsInWindow };
+}

package/dist/types.d.ts

@@ -25,7 +25,7 @@ export interface PluginInfo {
     status?: 'enabled' | 'disabled';
 }
 export type IssueTier = 1 | 2 | 3;
-export type IssueType = 'broken_symlink' | 'template' | 'skill_dup' | 'duplicate' | 'oversized_memory' | 'oversized_skill' | 'disabled_plugin' | 'stale_project' | 'temp_cache';
+export type IssueType = 'broken_symlink' | 'template' | 'skill_dup' | 'duplicate' | 'oversized_memory' | 'oversized_skill' | 'unused_skill' | 'disabled_plugin' | 'stale_project' | 'temp_cache';
 export interface Issue {
     type: IssueType;
     tier: IssueTier;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-slim",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Analyze and reduce Claude Code token overhead",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
     "dev": "tsc --watch",
     "test": "vitest run",
     "test:watch": "vitest",
+    "demo": "npm run build && bash scripts/demo/fixture.sh && vhs scripts/demo/demo.tape",
     "prepublishOnly": "npm run build"
   },
   "keywords": [
@@ -39,7 +40,7 @@
     "url": "https://github.com/iops-leo/claude-slim/issues"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "dependencies": {
     "commander": "^13.0.0",