claude-slim 2.2.2 → 2.3.0

package/README.md

@@ -2,9 +2,13 @@
 
 # claude-slim
 
+[![npm](https://img.shields.io/npm/v/claude-slim.svg)](https://www.npmjs.com/package/claude-slim)
+[![CI](https://github.com/iops-leo/claude-slim/actions/workflows/ci.yml/badge.svg)](https://github.com/iops-leo/claude-slim/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/claude-slim.svg)](./LICENSE)
+
 **You're burning thousands of tokens before you even say "hello."**
 
-Every session loads *every* skill, memory file, and plugin instruction into the system prompt — even the ones you never use. claude-slim finds and removes that waste.
+Every Claude Code session auto-loads every skill, memory file, and plugin instruction into the system prompt — even the ones you never use. If you run OMC, marketplace plugins, or a custom skill stack, you're paying for context you'll never touch. claude-slim finds and removes that waste.
 
 ```
 /claude-slim
@@ -115,21 +119,23 @@ That's slower responses. Hitting your usage cap faster. Paying for context you'r
 
 ---
 
-## Install (10 seconds)
+## Try it (10 seconds)
+
+No install needed — run once and see what's in your `~/.claude/`:
 
 ```bash
-claude plugin marketplace add iops-leo/claude-slim
-claude plugin install claude-slim
+npx claude-slim scan
 ```
 
-Then just type `/claude-slim` in any session.
-
-Or use the standalone CLI:
+Happy with what you see? Make it part of your Claude Code workflow:
 
 ```bash
-npx claude-slim scan
+claude plugin marketplace add iops-leo/claude-slim
+claude plugin install claude-slim
 ```
 
+Then just type `/claude-slim` in any session.
+
 ---
 
 ## Usage
@@ -162,6 +168,17 @@ npx claude-slim report            # Show savings from last clean
 | **Reversible** | `/claude-slim restore` brings anything back, any time |
 | **User-controlled** | Always asks before making changes. `--dry-run` to preview. |
 | **Hands off** | Never touches CLAUDE.md, settings.json, or plugin configs |
+| **Scoped** | All operations are refused if the target path escapes `~/.claude/` |
+
+### What claude-slim never touches
+
+- **`~/.claude/CLAUDE.md`** — your system instructions, read-only.
+- **`~/.claude/settings.json`** — MCP server config, hooks, and any other settings. Read-only.
+- **Plugin internals** (`~/.claude/plugins/config.json`, individual `plugin.json` files) — left alone; use `claude plugin` to manage plugins.
+- **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).
 
 ---
 

package/dist/cleaner.js

@@ -1,7 +1,7 @@
 import { rename, readdir, rmdir, rm, unlink, lstat, mkdir } from 'node:fs/promises';
 import { join, dirname } from 'node:path';
 import { appendManifest, ensureDisabledDir, getDisabledDir, removeEntry } from './manifest.js';
-import { getSkillsDir } from './paths.js';
+import { assertInsideClaudeDir, getSkillsDir } from './paths.js';
 async function pathExists(p) {
     try {
         await lstat(p);
@@ -33,6 +33,7 @@ export async function cleanIssues(issues) {
     const errors = [];
     for (const issue of issues) {
         try {
+            assertInsideClaudeDir(issue.path);
             if (issue.type === 'broken_symlink') {
                 await unlink(issue.path);
                 const entry = {
@@ -67,8 +68,17 @@ export async function cleanIssues(issues) {
                 moved.push(entry);
             }
             else if (issue.type === 'temp_cache') {
-                // Delete temp directories (failed plugin installs, not restorable)
-                await rm(issue.path, { recursive: true, force: true });
+                // Delete temp directories (failed plugin installs, not restorable).
+                // If the path is itself a symlink, only remove the link — never
+                // follow it into whatever it points at. fs.rm on Node >=18 already
+                // behaves this way, but we encode the invariant explicitly.
+                const st = await lstat(issue.path);
+                if (st.isSymbolicLink()) {
+                    await unlink(issue.path);
+                }
+                else {
+                    await rm(issue.path, { recursive: true, force: true });
+                }
                 const entry = {
                     date: new Date().toISOString(),
                     name: issue.name,
@@ -138,6 +148,7 @@ async function cleanEmptyDirs(dir) {
     catch { /* skip */ }
 }
 export async function restoreItem(entry) {
+    assertInsideClaudeDir(entry.from);
     if (entry.type === 'broken_symlink') {
         throw new Error(`Broken symlinks cannot be restored (${entry.name})`);
     }
@@ -163,6 +174,14 @@ export async function restoreItem(entry) {
         // Restore skill directory using the same naming as cleanIssues
         const safeName = entry.name.replace(/\//g, '--');
         const src = join(disabledDir, safeName);
+        if (!(await pathExists(src))) {
+            throw new Error(`Backup not found for "${entry.name}" at ${src}. ` +
+                `It may have been manually removed.`);
+        }
+        if (await pathExists(entry.from)) {
+            throw new Error(`Cannot restore: ${entry.from} already exists. ` +
+                `Remove or rename it first.`);
+        }
         await mkdir(dirname(entry.from), { recursive: true });
         await rename(src, entry.from);
     }

package/dist/paths.d.ts

@@ -5,3 +5,4 @@ export declare function getProjectsDir(): string;
 export declare function getDisabledDir(): string;
 export declare function getManifestPath(): string;
 export declare function getLegacyManifestPath(): string;
+export declare function assertInsideClaudeDir(p: string): void;

package/dist/paths.js

@@ -1,5 +1,5 @@
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve, sep } from 'node:path';
 export function getClaudeDir() {
     return join(homedir(), '.claude');
 }
@@ -21,3 +21,12 @@ export function getManifestPath() {
 export function getLegacyManifestPath() {
     return join(getDisabledDir(), '.claude-slim-manifest.jsonl');
 }
+// Refuse to operate on a path outside ~/.claude/. Guards destructive operations
+// (rename/rm/unlink) from acting on attacker-tampered manifests or scanner bugs.
+export function assertInsideClaudeDir(p) {
+    const resolved = resolve(p);
+    const root = resolve(getClaudeDir());
+    if (resolved !== root && !resolved.startsWith(root + sep)) {
+        throw new Error(`Refusing to operate on path outside ~/.claude/: ${p}`);
+    }
+}

package/dist/report.js

@@ -28,25 +28,25 @@ export function calculateReport(scanBefore, scanAfter, movedEntries, sessionsPer
             label: 'Local skills',
             before: String(localBefore),
             after: String(localAfter),
-            saved: `${localAfter - localBefore}`,
+            saved: `${localBefore - localAfter}`,
         },
         {
             label: 'System prompt',
             before: `~${promptBefore}`,
             after: `~${promptAfter}`,
-            saved: `${promptAfter - promptBefore}`,
+            saved: `${promptBefore - promptAfter}`,
         },
         {
             label: 'Memory files',
             before: `${(memBefore / 1024).toFixed(1)}KB`,
             after: `${(memAfter / 1024).toFixed(1)}KB`,
-            saved: `${((memAfter - memBefore) / 1024).toFixed(1)}KB`,
+            saved: `${((memBefore - memAfter) / 1024).toFixed(1)}KB`,
         },
         {
             label: 'Est. tokens',
             before: `~${before.toLocaleString()}`,
             after: `~${after.toLocaleString()}`,
-            saved: `~${(after - before).toLocaleString()}`,
+            saved: `~${(before - after).toLocaleString()}`,
         },
     ];
     return {

package/dist/scanner/claude-md.d.ts

@@ -0,0 +1,5 @@
+export declare function parseClaudeMdSections(content: string): Array<{
+    name: string;
+    sizeBytes: number;
+    tokens: number;
+}>;

package/dist/scanner/claude-md.js

@@ -0,0 +1,45 @@
+import { countTokensCached } from '../tokenizer.js';
+export function parseClaudeMdSections(content) {
+    const sections = [];
+    const lines = content.split('\n');
+    let currentName = null;
+    let currentContent = '';
+    for (const line of lines) {
+        if (line.startsWith('# ')) {
+            if (currentName !== null) {
+                sections.push({
+                    name: currentName,
+                    sizeBytes: Buffer.byteLength(currentContent),
+                    tokens: countTokensCached(currentContent, `claude-md-section:${currentName}`),
+                });
+            }
+            else if (currentContent.trim()) {
+                sections.push({
+                    name: '(preamble)',
+                    sizeBytes: Buffer.byteLength(currentContent),
+                    tokens: countTokensCached(currentContent, 'claude-md-section:preamble'),
+                });
+            }
+            currentName = line.slice(2).trim().slice(0, 60);
+            currentContent = line + '\n';
+        }
+        else {
+            currentContent += line + '\n';
+        }
+    }
+    if (currentName !== null) {
+        sections.push({
+            name: currentName,
+            sizeBytes: Buffer.byteLength(currentContent),
+            tokens: countTokensCached(currentContent, `claude-md-section:${currentName}`),
+        });
+    }
+    else if (currentContent.trim()) {
+        sections.push({
+            name: '(preamble)',
+            sizeBytes: Buffer.byteLength(currentContent),
+            tokens: countTokensCached(currentContent, 'claude-md-section:preamble'),
+        });
+    }
+    return sections;
+}

package/dist/scanner/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const STALE_DAYS = 90;
+export declare const OVERSIZED_SKILL_BYTES = 10240;
+export declare const OVERSIZED_MEMORY_BYTES = 5120;
+export declare const SKILL_PROMPT_OVERHEAD_TOKENS = 30;

package/dist/scanner/constants.js

@@ -0,0 +1,4 @@
+export const STALE_DAYS = 90;
+export const OVERSIZED_SKILL_BYTES = 10240;
+export const OVERSIZED_MEMORY_BYTES = 5120;
+export const SKILL_PROMPT_OVERHEAD_TOKENS = 30;

package/dist/scanner/detectors.d.ts

@@ -0,0 +1,20 @@
+import type { SkillInfo, BrokenSymlink, MemoryFile, PluginInfo, Issue } from '../types.js';
+import type { TempCache } from './plugin-skills.js';
+import type { StaleProject } from './memory.js';
+export interface DetectorContext {
+    localSkills: SkillInfo[];
+    pluginSkills: SkillInfo[];
+    brokenSymlinks: BrokenSymlink[];
+    memoryFiles: MemoryFile[];
+    tempCaches: TempCache[];
+    staleProjects: StaleProject[];
+    disabledPlugins: Set<string>;
+    plugins: PluginInfo[];
+    contents: Map<string, string>;
+}
+export interface Detector {
+    name: string;
+    detect(ctx: DetectorContext): Issue[];
+}
+export declare const detectors: Detector[];
+export declare function classifyIssues(ctx: DetectorContext, registry?: Detector[]): Issue[];

package/dist/scanner/detectors.js

@@ -0,0 +1,183 @@
+import { join } from 'node:path';
+import { getPluginsDir } from '../paths.js';
+import { OVERSIZED_SKILL_BYTES, OVERSIZED_MEMORY_BYTES, SKILL_PROMPT_OVERHEAD_TOKENS, } from './constants.js';
+const brokenSymlinkDetector = {
+    name: 'broken_symlink',
+    detect({ brokenSymlinks }) {
+        return brokenSymlinks.map((link) => ({
+            type: 'broken_symlink',
+            tier: 1,
+            name: link.name,
+            detail: link.target,
+            tokens: 0,
+            path: link.path,
+        }));
+    },
+};
+const templateDetector = {
+    name: 'template',
+    detect({ localSkills, contents }) {
+        const issues = [];
+        for (const skill of localSkills) {
+            const skillMdPath = join(skill.path, 'SKILL.md');
+            const content = contents.get(skillMdPath);
+            if (content && content.includes('Replace with description')) {
+                issues.push({
+                    type: 'template',
+                    tier: 1,
+                    name: skill.name,
+                    tokens: skill.tokens,
+                    path: skill.path,
+                });
+            }
+        }
+        return issues;
+    },
+};
+const duplicateDetector = {
+    name: 'duplicate',
+    detect({ localSkills, pluginSkills }) {
+        const pluginSkillNames = new Set(pluginSkills.map((s) => s.name));
+        const issues = [];
+        for (const skill of localSkills) {
+            // Check base name for nested skills (e.g. "org/ship" → "ship")
+            const baseName = skill.name.includes('/') ? skill.name.split('/').pop() : skill.name;
+            if (pluginSkillNames.has(baseName)) {
+                issues.push({
+                    type: 'duplicate',
+                    tier: 2,
+                    name: skill.name,
+                    detail: 'local+plugin',
+                    tokens: skill.tokens,
+                    path: skill.path,
+                });
+            }
+        }
+        return issues;
+    },
+};
+const oversizedSkillDetector = {
+    name: 'oversized_skill',
+    detect({ localSkills }) {
+        const issues = [];
+        for (const skill of localSkills) {
+            if (skill.sizeBytes > OVERSIZED_SKILL_BYTES) {
+                issues.push({
+                    type: 'oversized_skill',
+                    tier: 3,
+                    name: skill.name,
+                    detail: `${Math.round(skill.sizeBytes / 1024)}KB`,
+                    tokens: skill.tokens,
+                    path: skill.path,
+                });
+            }
+        }
+        return issues;
+    },
+};
+const skillDupDetector = {
+    name: 'skill_dup',
+    detect({ localSkills }) {
+        const issues = [];
+        for (const skill of localSkills) {
+            const dotSkillDir = skill.path + '.skill';
+            if (localSkills.some((s) => s.path === dotSkillDir)) {
+                issues.push({
+                    type: 'skill_dup',
+                    tier: 1,
+                    name: skill.name,
+                    tokens: 0,
+                    path: dotSkillDir,
+                });
+            }
+        }
+        return issues;
+    },
+};
+const tempCacheDetector = {
+    name: 'temp_cache',
+    detect({ tempCaches }) {
+        return tempCaches.map((temp) => ({
+            type: 'temp_cache',
+            tier: 1,
+            name: temp.name,
+            detail: `${temp.sizeKB}KB`,
+            tokens: 0,
+            path: temp.path,
+        }));
+    },
+};
+const oversizedMemoryDetector = {
+    name: 'oversized_memory',
+    detect({ memoryFiles }) {
+        const issues = [];
+        for (const mem of memoryFiles) {
+            if (mem.sizeBytes > OVERSIZED_MEMORY_BYTES) {
+                issues.push({
+                    type: 'oversized_memory',
+                    tier: 2,
+                    name: `${mem.project}/${mem.name}`,
+                    detail: `${Math.round(mem.sizeBytes / 1024)}KB`,
+                    tokens: mem.tokens,
+                    path: mem.path,
+                });
+            }
+        }
+        return issues;
+    },
+};
+const staleProjectDetector = {
+    name: 'stale_project',
+    detect({ staleProjects, memoryFiles }) {
+        return staleProjects.map((stale) => {
+            const memTokens = memoryFiles
+                .filter((m) => m.project === stale.project)
+                .reduce((sum, m) => sum + m.tokens, 0);
+            return {
+                type: 'stale_project',
+                tier: 2,
+                name: stale.project,
+                detail: `${stale.ageDays}d, ${stale.fileCount} files, ${Math.round(stale.totalBytes / 1024)}KB`,
+                tokens: memTokens,
+                path: stale.path,
+            };
+        });
+    },
+};
+const disabledPluginDetector = {
+    name: 'disabled_plugin',
+    detect({ plugins, disabledPlugins }) {
+        const issues = [];
+        for (const plugin of plugins) {
+            if (disabledPlugins.has(plugin.name)) {
+                issues.push({
+                    type: 'disabled_plugin',
+                    tier: 2,
+                    name: plugin.name,
+                    detail: `${plugin.skillCount} skills`,
+                    tokens: plugin.skillCount * SKILL_PROMPT_OVERHEAD_TOKENS,
+                    path: join(getPluginsDir(), plugin.name),
+                });
+            }
+        }
+        return issues;
+    },
+};
+// The full registry. Order only matters for ties in the tier sort.
+// New detectors: define above, add here, update CONTRIBUTING.md's issue-type table.
+export const detectors = [
+    brokenSymlinkDetector,
+    templateDetector,
+    duplicateDetector,
+    oversizedSkillDetector,
+    skillDupDetector,
+    tempCacheDetector,
+    oversizedMemoryDetector,
+    staleProjectDetector,
+    disabledPluginDetector,
+];
+export function classifyIssues(ctx, registry = detectors) {
+    const issues = registry.flatMap((d) => d.detect(ctx));
+    issues.sort((a, b) => a.tier - b.tier);
+    return issues;
+}

package/dist/scanner/disabled-plugins.d.ts

@@ -0,0 +1,2 @@
+export declare function parseDisabledPlugins(output: string): Set<string>;
+export declare function getDisabledPlugins(): Promise<Set<string>>;

package/dist/scanner/disabled-plugins.js

@@ -0,0 +1,26 @@
+import { runCommand } from './fs-walk.js';
+export function parseDisabledPlugins(output) {
+    const disabled = new Set();
+    if (!output)
+        return disabled;
+    let currentName = null;
+    for (const line of output.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('❯')) {
+            const full = trimmed.split('❯')[1]?.trim() || '';
+            // Format: sub-plugin@marketplace — extract marketplace name for cache dir matching
+            currentName = full.includes('@') ? full.split('@')[1] : full;
+        }
+        else if (trimmed.toLowerCase().includes('disabled') && currentName) {
+            disabled.add(currentName);
+            currentName = null;
+        }
+        else if (trimmed.toLowerCase().includes('enabled')) {
+            currentName = null;
+        }
+    }
+    return disabled;
+}
+export async function getDisabledPlugins() {
+    return parseDisabledPlugins(await runCommand('claude', ['plugin', 'list']));
+}

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

@@ -0,0 +1,7 @@
+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>;
+export declare function isBrokenSymlink(p: string): Promise<boolean>;
+export declare function resolveRealPath(p: string): Promise<string>;
+export declare function getDirSize(dir: string): Promise<number>;
+export declare function runCommand(file: string, args: string[]): Promise<string>;

package/dist/scanner/fs-walk.js

@@ -0,0 +1,82 @@
+import { readFile, readdir, lstat, realpath, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function safeReadFile(p) {
+    try {
+        return await readFile(p, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+export async function safeReaddir(p) {
+    try {
+        return await readdir(p);
+    }
+    catch {
+        return [];
+    }
+}
+export async function isDirectory(p) {
+    try {
+        return (await stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export async function isBrokenSymlink(p) {
+    try {
+        const lstats = await lstat(p);
+        if (!lstats.isSymbolicLink())
+            return false;
+        await realpath(p);
+        return false;
+    }
+    catch {
+        try {
+            return (await lstat(p)).isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+    }
+}
+export async function resolveRealPath(p) {
+    try {
+        return await realpath(p);
+    }
+    catch {
+        return p;
+    }
+}
+export async function getDirSize(dir) {
+    let total = 0;
+    const entries = await safeReaddir(dir);
+    for (const entry of entries) {
+        const p = join(dir, entry);
+        try {
+            const s = await stat(p);
+            if (s.isFile())
+                total += s.size;
+            else if (s.isDirectory())
+                total += await getDirSize(p);
+        }
+        catch { /* skip */ }
+    }
+    return total;
+}
+// execFile (not exec) — never routes through a shell, so command arguments
+// cannot be interpreted as shell metacharacters regardless of caller inputs.
+export async function runCommand(file, args) {
+    try {
+        const { execFile } = await import('node:child_process');
+        return new Promise((resolve) => {
+            execFile(file, args, { timeout: 10000 }, (_err, stdout) => {
+                resolve(stdout || '');
+            });
+        });
+    }
+    catch {
+        return '';
+    }
+}

package/dist/scanner/index.d.ts

@@ -0,0 +1,2 @@
+import type { ScanResult } from '../types.js';
+export declare function scan(): Promise<ScanResult>;

package/dist/scanner/index.js

@@ -0,0 +1,55 @@
+import { join } from 'node:path';
+import { countTokensCached } from '../tokenizer.js';
+import { getClaudeDir } from '../paths.js';
+import { safeReadFile } from './fs-walk.js';
+import { scanLocalSkills } from './local-skills.js';
+import { scanPluginSkills } from './plugin-skills.js';
+import { scanMemoryFiles } from './memory.js';
+import { scanMcpServers } from './mcp.js';
+import { parseClaudeMdSections } from './claude-md.js';
+import { getDisabledPlugins } from './disabled-plugins.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([
+        scanLocalSkills(),
+        scanPluginSkills(),
+        scanMemoryFiles(),
+        scanMcpServers(),
+        getDisabledPlugins(),
+    ]);
+    // Annotate plugin status
+    for (const plugin of plugins) {
+        plugin.status = disabledPlugins.has(plugin.name) ? 'disabled' : 'enabled';
+    }
+    // CLAUDE.md
+    const claudeMdContent = await safeReadFile(join(getClaudeDir(), 'CLAUDE.md'));
+    const claudeMdBytes = claudeMdContent ? Buffer.byteLength(claudeMdContent) : 0;
+    const claudeMdTokens = claudeMdContent
+        ? countTokensCached(claudeMdContent, join(getClaudeDir(), 'CLAUDE.md'))
+        : 0;
+    const claudeMdSections = claudeMdContent ? parseClaudeMdSections(claudeMdContent) : [];
+    const issues = classifyIssues({
+        localSkills, pluginSkills, brokenSymlinks, memoryFiles,
+        tempCaches, staleProjects, disabledPlugins, plugins,
+        contents,
+    });
+    // Estimate total tokens at startup
+    const skillListingTokens = (localSkills.length + pluginSkills.length) * SKILL_PROMPT_OVERHEAD_TOKENS;
+    const memoryTokens = memoryFiles.reduce((sum, m) => sum + m.tokens, 0);
+    const totalTokensBefore = skillListingTokens + claudeMdTokens + memoryTokens;
+    return {
+        localSkills,
+        pluginSkills,
+        plugins,
+        brokenSymlinks,
+        memoryFiles,
+        claudeMdBytes,
+        claudeMdTokens,
+        claudeMdSections,
+        mcpServers: mcp.count,
+        mcpServerNames: mcp.names,
+        issues,
+        totalTokensBefore,
+    };
+}

package/dist/scanner/local-skills.d.ts

@@ -0,0 +1,12 @@
+import type { SkillInfo, BrokenSymlink } from '../types.js';
+export interface SkillCandidate {
+    skill: SkillInfo;
+    realMdPath: string;
+}
+export declare function dedupeBySymlink(candidates: SkillCandidate[]): SkillInfo[];
+export interface LocalSkillsResult {
+    skills: SkillInfo[];
+    brokenSymlinks: BrokenSymlink[];
+    contents: Map<string, string>;
+}
+export declare function scanLocalSkills(): Promise<LocalSkillsResult>;