claude-slim 2.2.3 → 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/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>;

package/dist/scanner/local-skills.js

@@ -0,0 +1,97 @@
+import { readlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { countTokensCached } from '../tokenizer.js';
+import { getSkillsDir } from '../paths.js';
+import { safeReadFile, safeReaddir, isDirectory, isBrokenSymlink, resolveRealPath, } from './fs-walk.js';
+export function dedupeBySymlink(candidates) {
+    const seen = new Map();
+    for (const { skill, realMdPath } of candidates) {
+        const existing = seen.get(realMdPath);
+        if (!existing) {
+            seen.set(realMdPath, skill);
+            continue;
+        }
+        // Prefer top-level name (no slash) over nested duplicate
+        const existingIsNested = existing.name.includes('/');
+        const currentIsNested = skill.name.includes('/');
+        if (existingIsNested && !currentIsNested) {
+            seen.set(realMdPath, skill);
+        }
+    }
+    return Array.from(seen.values());
+}
+export async function scanLocalSkills() {
+    const skillsDir = getSkillsDir();
+    const candidates = [];
+    const brokenSymlinks = [];
+    const contents = new Map();
+    const entries = await safeReaddir(skillsDir);
+    const scanPromises = entries.map(async (entry) => {
+        const dirPath = join(skillsDir, entry);
+        if (!(await isDirectory(dirPath)))
+            return;
+        const skillMd = join(dirPath, 'SKILL.md');
+        if (await isBrokenSymlink(skillMd)) {
+            let target = 'unknown';
+            try {
+                target = await readlink(skillMd);
+            }
+            catch { /* */ }
+            brokenSymlinks.push({ name: entry, path: skillMd, target });
+            return;
+        }
+        const content = await safeReadFile(skillMd);
+        if (content !== null) {
+            contents.set(skillMd, content);
+            const tokens = countTokensCached(content, skillMd);
+            const realMdPath = await resolveRealPath(skillMd);
+            candidates.push({
+                skill: {
+                    name: entry,
+                    path: dirPath,
+                    sizeBytes: Buffer.byteLength(content),
+                    tokens,
+                    source: 'local',
+                },
+                realMdPath,
+            });
+        }
+        // Nested skills (e.g., @internal-sys/commit-guide)
+        const subEntries = await safeReaddir(dirPath);
+        for (const sub of subEntries) {
+            const subDir = join(dirPath, sub);
+            if (!(await isDirectory(subDir)))
+                continue;
+            const subSkillMd = join(subDir, 'SKILL.md');
+            if (await isBrokenSymlink(subSkillMd)) {
+                let target = 'unknown';
+                try {
+                    target = await readlink(subSkillMd);
+                }
+                catch { /* */ }
+                brokenSymlinks.push({ name: `${entry}/${sub}`, path: subSkillMd, target });
+                continue;
+            }
+            const subContent = await safeReadFile(subSkillMd);
+            if (subContent !== null) {
+                const name = `${entry}/${sub}`;
+                contents.set(subSkillMd, subContent);
+                const tokens = countTokensCached(subContent, subSkillMd);
+                const realMdPath = await resolveRealPath(subSkillMd);
+                candidates.push({
+                    skill: {
+                        name,
+                        path: subDir,
+                        sizeBytes: Buffer.byteLength(subContent),
+                        tokens,
+                        source: 'local',
+                    },
+                    realMdPath,
+                });
+            }
+        }
+    });
+    await Promise.all(scanPromises);
+    const skills = dedupeBySymlink(candidates);
+    return { skills, brokenSymlinks, contents };
+}

package/dist/scanner/mcp.d.ts

@@ -0,0 +1,5 @@
+export interface McpScanResult {
+    count: number;
+    names: string[];
+}
+export declare function scanMcpServers(): Promise<McpScanResult>;

package/dist/scanner/mcp.js

@@ -0,0 +1,17 @@
+import { join } from 'node:path';
+import { getClaudeDir } from '../paths.js';
+import { safeReadFile } from './fs-walk.js';
+export async function scanMcpServers() {
+    const content = await safeReadFile(join(getClaudeDir(), 'settings.json'));
+    if (!content)
+        return { count: 0, names: [] };
+    try {
+        const data = JSON.parse(content);
+        const servers = data.mcpServers || {};
+        const names = Object.keys(servers).sort();
+        return { count: names.length, names };
+    }
+    catch {
+        return { count: 0, names: [] };
+    }
+}

package/dist/scanner/memory.d.ts

@@ -0,0 +1,13 @@
+import type { MemoryFile } from '../types.js';
+export interface StaleProject {
+    project: string;
+    path: string;
+    ageDays: number;
+    fileCount: number;
+    totalBytes: number;
+}
+export interface MemoryScanResult {
+    memoryFiles: MemoryFile[];
+    staleProjects: StaleProject[];
+}
+export declare function scanMemoryFiles(): Promise<MemoryScanResult>;