claude-slim 2.6.1 → 2.7.0

package/README.md

@@ -67,6 +67,7 @@ That's slower responses. Hitting your usage cap faster. Paying for context you'r
 | 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)** |
+| **Unused plugins** | **Plugins whose skill/mcp/cmd were never invoked in your last N days of sessions (default 60d). Tier 3, never auto-selected.** |
 | 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 |
@@ -210,6 +211,13 @@ From a real cleanup session:
 
 ---
 
+## v2.7 — What's new
+
+- **Unused-plugin detection** — claude-slim now reads your session transcripts for MCP tool calls (`mcp__plugin_<plugin>_<server>__*`) and slash commands, and flags plugins whose surfaces you've never touched in the last 60 days. Tier 3 (Optional, never auto-selected). When you choose to clean one, `claude plugin disable <name>` runs automatically; `/claude-slim restore` re-enables it.
+- **PLUGIN BREAKDOWN table** — the scan report now includes a per-plugin cost breakdown: token estimate (CLAUDE.md section + skills + deferred MCP tools + commands) and usage status (used / unused / agent-only / insufficient data / disabled). In the owner's real env: `oh-my-claudecode` tops the list at ~6,210 tok; three plugins were flagged as unused despite being enabled.
+- **Session parser fix** — slash commands in string-form user messages were previously missed (only array-form content was parsed). All slash-command invocations are now captured correctly.
+- **+82 tests** for the new modules and the parser regression.
+
 ## v2.6 — What's new
 
 - **`claude-slim doctor`** — Checks Node support, `~/.claude/` readability, local skill/plugin cache access, `claude plugin list`, and recent session-log signal quality. Use it when scan results look sparse or unused-skill detection is suppressed.

package/dist/cleaner.d.ts

@@ -1,4 +1,4 @@
-import type { Issue, ManifestEntry } from './types.js';
+import type { Issue, ManifestEntry, DisabledPluginEntry } from './types.js';
 export interface CleanResult {
     moved: ManifestEntry[];
     skipped: string[];
@@ -8,4 +8,4 @@ export interface CleanResult {
     }>;
 }
 export declare function cleanIssues(issues: Issue[]): Promise<CleanResult>;
-export declare function restoreItem(entry: ManifestEntry): Promise<void>;
+export declare function restoreItem(entry: ManifestEntry | DisabledPluginEntry): Promise<void>;

package/dist/cleaner.js

@@ -1,7 +1,8 @@
 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 { appendManifest, ensureDisabledDir, getDisabledDir, removeEntry, recordDisabledPlugin, removeDisabledPlugin } from './manifest.js';
 import { assertInsideClaudeDir, getSkillsDir } from './paths.js';
+import { disablePlugin, enablePlugin } from './plugin-runtime.js';
 async function pathExists(p) {
     try {
         await lstat(p);
@@ -33,7 +34,10 @@ export async function cleanIssues(issues) {
     const errors = [];
     for (const issue of issues) {
         try {
-            assertInsideClaudeDir(issue.path);
+            // unused_plugin and report-only types don't touch filesystem paths directly
+            if (issue.type !== 'unused_plugin' && issue.type !== 'oversized_memory' && issue.type !== 'disabled_plugin') {
+                assertInsideClaudeDir(issue.path);
+            }
             if (issue.type === 'broken_symlink') {
                 await unlink(issue.path);
                 const entry = {
@@ -114,6 +118,19 @@ export async function cleanIssues(issues) {
                 await recordOrRollback(entry, () => rename(backupDir, issue.path));
                 moved.push(entry);
             }
+            else if (issue.type === 'unused_plugin') {
+                await disablePlugin(issue.name);
+                // Record in manifest; if that fails, roll back the disable
+                try {
+                    await recordDisabledPlugin(issue.name, issue.marketplace ?? 'unknown');
+                }
+                catch (e) {
+                    await enablePlugin(issue.name).catch(() => { });
+                    throw e;
+                }
+                // unused_plugin doesn't contribute to moved (no ManifestEntry shape), track skipped
+                skipped.push(issue.name);
+            }
             else if (issue.type === 'oversized_memory' || issue.type === 'disabled_plugin') {
                 // Report only — user manages these manually
                 skipped.push(issue.name);
@@ -149,42 +166,50 @@ 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})`);
+    // Handle new-style disabled_plugin entries (plugin + marketplace shape)
+    if ('plugin' in entry && 'marketplace' in entry) {
+        const pluginEntry = entry;
+        await enablePlugin(pluginEntry.plugin);
+        await removeDisabledPlugin(pluginEntry.plugin, pluginEntry.marketplace);
+        return;
+    }
+    const legacyEntry = entry;
+    assertInsideClaudeDir(legacyEntry.from);
+    if (legacyEntry.type === 'broken_symlink') {
+        throw new Error(`Broken symlinks cannot be restored (${legacyEntry.name})`);
     }
-    if (entry.type === 'disabled_plugin') {
-        throw new Error(`Plugins must be reinstalled: claude plugin install ${entry.name}`);
+    if (legacyEntry.type === 'disabled_plugin') {
+        throw new Error(`Plugins must be reinstalled: claude plugin install ${legacyEntry.name}`);
     }
-    if (entry.type === 'temp_cache') {
-        throw new Error(`Temp caches were deleted and cannot be restored (${entry.name})`);
+    if (legacyEntry.type === 'temp_cache') {
+        throw new Error(`Temp caches were deleted and cannot be restored (${legacyEntry.name})`);
     }
     const disabledDir = getDisabledDir();
-    if (entry.type === 'stale_project') {
-        const backupDir = join(disabledDir, 'memory-backup', entry.name);
+    if (legacyEntry.type === 'stale_project') {
+        const backupDir = join(disabledDir, 'memory-backup', legacyEntry.name);
         // Refuse to overwrite user's current state
-        if (await pathExists(entry.from)) {
-            throw new Error(`Cannot restore: ${entry.from} already exists. ` +
+        if (await pathExists(legacyEntry.from)) {
+            throw new Error(`Cannot restore: ${legacyEntry.from} already exists. ` +
                 `Remove or rename it first.`);
         }
-        await mkdir(dirname(entry.from), { recursive: true });
+        await mkdir(dirname(legacyEntry.from), { recursive: true });
         // Atomic directory rename — requires same FS (guaranteed since both paths are under ~/.claude/)
-        await rename(backupDir, entry.from);
+        await rename(backupDir, legacyEntry.from);
     }
     else {
         // Restore skill directory using the same naming as cleanIssues
-        const safeName = entry.name.replace(/\//g, '--');
+        const safeName = legacyEntry.name.replace(/\//g, '--');
         const src = join(disabledDir, safeName);
         if (!(await pathExists(src))) {
-            throw new Error(`Backup not found for "${entry.name}" at ${src}. ` +
+            throw new Error(`Backup not found for "${legacyEntry.name}" at ${src}. ` +
                 `It may have been manually removed.`);
         }
-        if (await pathExists(entry.from)) {
-            throw new Error(`Cannot restore: ${entry.from} already exists. ` +
+        if (await pathExists(legacyEntry.from)) {
+            throw new Error(`Cannot restore: ${legacyEntry.from} already exists. ` +
                 `Remove or rename it first.`);
         }
-        await mkdir(dirname(entry.from), { recursive: true });
-        await rename(src, entry.from);
+        await mkdir(dirname(legacyEntry.from), { recursive: true });
+        await rename(src, legacyEntry.from);
     }
-    await removeEntry(entry.name);
+    await removeEntry(legacyEntry.name);
 }

package/dist/cli.js

@@ -73,12 +73,17 @@ program
     .command('restore')
     .description('Restore previously disabled items')
     .action(async () => {
-    const entries = await readManifest();
+    const allEntries = await readManifest();
+    // Separate plugin entries (DisabledPluginEntry shape) from legacy ManifestEntry
+    const pluginEntries = allEntries.filter((e) => 'plugin' in e && 'marketplace' in e);
+    const legacyEntries = allEntries.filter((e) => !('plugin' in e && 'marketplace' in e));
     // v2 manifest contains only currently-disabled entries (restored ones are removed)
-    const disabled = entries.filter((e) => e.type !== 'broken_symlink');
+    const disabled = legacyEntries.filter((e) => e.type !== 'broken_symlink');
     const NON_RESTORABLE = new Set(['temp_cache', 'disabled_plugin']);
-    const restorable = disabled.filter((e) => !NON_RESTORABLE.has(e.type));
+    const restorableLegacy = disabled.filter((e) => !NON_RESTORABLE.has(e.type));
     const infoOnly = disabled.filter((e) => NON_RESTORABLE.has(e.type));
+    // Combine restorable: legacy skill/project entries + plugin entries
+    const restorable = [...restorableLegacy, ...pluginEntries];
     if (restorable.length === 0 && infoOnly.length === 0) {
         console.log('\n  Nothing to restore.\n');
         return;
@@ -87,8 +92,16 @@ program
         console.log('\n  Restorable items:\n');
         for (let i = 0; i < restorable.length; i++) {
             const e = restorable[i];
-            const date = new Date(e.date).toLocaleDateString();
-            console.log(`    ${i + 1}. ${e.name} (${e.type}, disabled ${date})`);
+            if ('plugin' in e && 'marketplace' in e) {
+                const pe = e;
+                const date = new Date(pe.disabledAt).toLocaleDateString();
+                console.log(`    ${i + 1}. [plugin] ${pe.plugin} @ ${pe.marketplace} (disabled ${date})`);
+            }
+            else {
+                const le = e;
+                const date = new Date(le.date).toLocaleDateString();
+                console.log(`    ${i + 1}. ${le.name} (${le.type}, disabled ${date})`);
+            }
         }
     }
     if (infoOnly.length > 0) {
@@ -98,7 +111,7 @@ program
             const hint = e.type === 'disabled_plugin'
                 ? `reinstall: claude plugin install ${e.name}`
                 : 'deleted, cannot restore';
-            console.log(`    \x1b[90m\u2022 ${e.name} (${date}) — ${hint}\x1b[0m`);
+            console.log(`    \x1b[90m• ${e.name} (${date}) — ${hint}\x1b[0m`);
         }
     }
     if (restorable.length === 0) {
@@ -114,14 +127,18 @@ program
     }
     let restored = 0;
     for (const idx of indices) {
+        const e = restorable[idx];
+        const label = 'plugin' in e && 'marketplace' in e
+            ? e.plugin
+            : e.name;
         try {
-            await restoreItem(restorable[idx]);
-            console.log(`  \x1b[32m\u2713\x1b[0m Restored: ${restorable[idx].name}`);
+            await restoreItem(e);
+            console.log(`  \x1b[32m✓\x1b[0m Restored: ${label}`);
             restored++;
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            console.log(`  \x1b[31m\u2717\x1b[0m ${restorable[idx].name}: ${msg}`);
+            console.log(`  \x1b[31m✗\x1b[0m ${label}: ${msg}`);
         }
     }
     console.log(`\n  Restored ${restored} item(s).\n`);
@@ -135,7 +152,9 @@ program
     .action(async (opts) => {
     await initTokenizer();
     const result = await scan({ lookbackDays: parseInt(opts.lookbackDays, 10) || 60 });
-    const entries = await readManifest();
+    const allEntries = await readManifest();
+    // Filter to legacy-style entries only (those with tokenCount/name/from fields)
+    const entries = allEntries.filter((e) => !('plugin' in e && 'marketplace' in e));
     const movedEntries = entries.filter((e) => e.tokenCount && e.tokenCount > 0);
     if (movedEntries.length === 0) {
         console.log('\n  No previous cleanup found. Run `claude-slim clean` first.\n');
@@ -195,10 +214,10 @@ async function runCleanPipeline(opts) {
     let selectedIssues;
     if (isInteractive) {
         console.log('  Actions:');
-        console.log('    Enter    \u2192 accept pre-selected (Tier 1 only)');
-        console.log('    1,3,5    \u2192 select specific items');
-        console.log('    all      \u2192 select everything');
-        console.log('    none     \u2192 cancel');
+        console.log('    Enter    → accept pre-selected (Tier 1 only)');
+        console.log('    1,3,5    → select specific items');
+        console.log('    all      → select everything');
+        console.log('    none     → cancel');
         console.log('');
         const selection = await askUser('  Your choice: ');
         selectedIssues = resolveSelection(selection, result.issues);
@@ -207,10 +226,10 @@ async function runCleanPipeline(opts) {
         // Auto mode or non-TTY: select Tier 1 only
         selectedIssues = result.issues.filter((i) => i.tier === 1);
         if (!opts.auto) {
-            console.log('  \x1b[33m\u26a0 Non-interactive mode detected, auto-selecting Tier 1\x1b[0m\n');
+            console.log('  \x1b[33m⚠ Non-interactive mode detected, auto-selecting Tier 1\x1b[0m\n');
         }
         else {
-            console.log(`  \x1b[36m\u2192 Auto mode: selecting ${selectedIssues.length} Tier 1 item(s)\x1b[0m\n`);
+            console.log(`  \x1b[36m→ Auto mode: selecting ${selectedIssues.length} Tier 1 item(s)\x1b[0m\n`);
         }
     }
     if (selectedIssues.length === 0) {
@@ -221,7 +240,7 @@ async function runCleanPipeline(opts) {
     if (opts.dryRun) {
         console.log('\n  \x1b[33m[DRY RUN]\x1b[0m Would disable:');
         for (const issue of selectedIssues) {
-            console.log(`    \u2022 ${issue.name} (${issue.type})`);
+            console.log(`    • ${issue.name} (${issue.type})`);
         }
         console.log(`\n  Estimated token savings: ~${selectedIssues.reduce((s, i) => s + i.tokens, 0).toLocaleString()}`);
         console.log('');
@@ -239,7 +258,7 @@ async function runCleanPipeline(opts) {
     if (cleanResult.errors.length > 0) {
         console.log('  \x1b[31mErrors:\x1b[0m');
         for (const err of cleanResult.errors) {
-            console.log(`    \u2022 ${err.name}: ${err.error}`);
+            console.log(`    • ${err.name}: ${err.error}`);
         }
         console.log('');
     }

package/dist/manifest.d.ts

@@ -1,10 +1,13 @@
-import type { Manifest, ManifestEntry } from './types.js';
+import type { Manifest, ManifestEntry, AnyManifestEntry, DisabledPluginEntry } from './types.js';
 export declare function getDisabledDir(): string;
 export declare function ensureDisabledDir(): Promise<void>;
 export declare function migrateLegacyIfNeeded(): Promise<void>;
 export declare function readManifestV2(): Promise<Manifest>;
 export declare function writeManifestV2(manifest: Manifest): Promise<void>;
-export declare function addEntry(entry: ManifestEntry): Promise<void>;
+export declare function addEntry(entry: AnyManifestEntry): Promise<void>;
 export declare function removeEntry(name: string): Promise<ManifestEntry | null>;
-export declare function readManifest(): Promise<ManifestEntry[]>;
-export declare function appendManifest(entry: ManifestEntry): Promise<void>;
+export declare function recordDisabledPlugin(plugin: string, marketplace: string): Promise<void>;
+export declare function findDisabledPlugin(plugin: string, marketplace: string): Promise<DisabledPluginEntry | undefined>;
+export declare function removeDisabledPlugin(plugin: string, marketplace: string): Promise<boolean>;
+export declare function readManifest(): Promise<AnyManifestEntry[]>;
+export declare function appendManifest(entry: AnyManifestEntry): Promise<void>;

package/dist/manifest.js

@@ -15,6 +15,9 @@ async function pathExists(p) {
         return false;
     }
 }
+function isDisabledPluginEntry(e) {
+    return e.type === 'disabled_plugin' && 'plugin' in e && 'marketplace' in e;
+}
 function parseJsonl(content) {
     const entries = [];
     for (const line of content.split('\n')) {
@@ -108,13 +111,35 @@ export async function addEntry(entry) {
 }
 export async function removeEntry(name) {
     const m = await readManifestV2();
-    const idx = m.entries.findIndex((e) => e.name === name);
+    const idx = m.entries.findIndex((e) => !isDisabledPluginEntry(e) && e.name === name);
     if (idx === -1)
         return null;
     const [removed] = m.entries.splice(idx, 1);
     await writeManifestV2(m);
     return removed;
 }
+export async function recordDisabledPlugin(plugin, marketplace) {
+    const entry = {
+        type: 'disabled_plugin',
+        plugin,
+        marketplace,
+        disabledAt: new Date().toISOString(),
+    };
+    await addEntry(entry);
+}
+export async function findDisabledPlugin(plugin, marketplace) {
+    const m = await readManifestV2();
+    return m.entries.find((e) => isDisabledPluginEntry(e) && e.plugin === plugin && e.marketplace === marketplace);
+}
+export async function removeDisabledPlugin(plugin, marketplace) {
+    const m = await readManifestV2();
+    const idx = m.entries.findIndex((e) => isDisabledPluginEntry(e) && e.plugin === plugin && e.marketplace === marketplace);
+    if (idx === -1)
+        return false;
+    m.entries.splice(idx, 1);
+    await writeManifestV2(m);
+    return true;
+}
 // --- Legacy-compatible API (still used by cleaner/cli pending Task 8) ---
 export async function readManifest() {
     const m = await readManifestV2();

package/dist/plugin-runtime.d.ts

@@ -0,0 +1,4 @@
+/** Validates plugin name then shells out to `claude plugin disable <name>`. */
+export declare function disablePlugin(name: string): Promise<void>;
+/** Validates plugin name then shells out to `claude plugin enable <name>`. */
+export declare function enablePlugin(name: string): Promise<void>;

package/dist/plugin-runtime.js

@@ -0,0 +1,33 @@
+import { execFile } from 'node:child_process';
+const PLUGIN_NAME_RE = /^[a-zA-Z0-9_-]+$/;
+function validateName(name) {
+    if (!PLUGIN_NAME_RE.test(name)) {
+        throw new Error(`Refusing to operate on suspicious plugin name: ${name}`);
+    }
+}
+function runPluginCommand(subcommand, name) {
+    return new Promise((resolve, reject) => {
+        execFile('claude', ['plugin', subcommand, name], { timeout: 30000 }, (err, _stdout, stderr) => {
+            if (err) {
+                const detail = stderr?.trim() ? `: ${stderr.trim()}` : '';
+                reject(new Error(`${err.message}${detail}`));
+                return;
+            }
+            if (stderr?.trim()) {
+                reject(new Error(stderr.trim()));
+                return;
+            }
+            resolve();
+        });
+    });
+}
+/** Validates plugin name then shells out to `claude plugin disable <name>`. */
+export async function disablePlugin(name) {
+    validateName(name);
+    return runPluginCommand('disable', name);
+}
+/** Validates plugin name then shells out to `claude plugin enable <name>`. */
+export async function enablePlugin(name) {
+    validateName(name);
+    return runPluginCommand('enable', name);
+}

package/dist/report.d.ts

@@ -1,4 +1,5 @@
-import type { ScanResult, ManifestEntry } from './types.js';
+import type { ScanResult, ManifestEntry, PluginBreakdown } from './types.js';
+import { formatPluginsTable } from './scanner/plugin-breakdown.js';
 export interface BreakdownRow {
     label: string;
     before: string;
@@ -17,7 +18,13 @@ export interface ReportData {
     monthlySavings: number;
     sessionsPerDay: number;
     breakdown: BreakdownRow[];
+    unusedPlugins: {
+        count: number;
+        tokens: number;
+    };
 }
 export declare function calculateReport(scanBefore: ScanResult, scanAfter: ScanResult, movedEntries: ManifestEntry[], sessionsPerDay?: number): ReportData;
 export declare function formatReportBox(data: ReportData): string;
 export declare function formatScanSummary(result: ScanResult): string;
+export { formatPluginsTable };
+export type { PluginBreakdown };

package/dist/report.js

@@ -1,5 +1,6 @@
 import { homedir } from 'node:os';
 import { isUsingFallback } from './tokenizer.js';
+import { formatPluginsTable } from './scanner/plugin-breakdown.js';
 // Claude Code encodes /Users/leo.new/foo as -Users-leo-new-foo
 const HOME_PREFIX = homedir().replace(/\//g, '-').replace(/\./g, '-');
 const SESSIONS_PER_DAY_DEFAULT = 2;
@@ -49,6 +50,11 @@ export function calculateReport(scanBefore, scanAfter, movedEntries, sessionsPer
             saved: `~${(before - after).toLocaleString()}`,
         },
     ];
+    const unusedPluginIssues = scanAfter.issues.filter((i) => i.type === 'unused_plugin');
+    const unusedPlugins = {
+        count: unusedPluginIssues.length,
+        tokens: unusedPluginIssues.reduce((s, i) => s + (i.tokens || 0), 0),
+    };
     return {
         before,
         after,
@@ -58,6 +64,7 @@ export function calculateReport(scanBefore, scanAfter, movedEntries, sessionsPer
         monthlySavings,
         sessionsPerDay,
         breakdown,
+        unusedPlugins,
     };
 }
 export function formatReportBox(data) {
@@ -69,7 +76,7 @@ export function formatReportBox(data) {
     };
     const top = '\u256d' + '\u2500'.repeat(W) + '\u256e';
     const bot = '\u2570' + '\u2500'.repeat(W) + '\u256f';
-    const blank = '\u2502' + ' '.repeat(W) + '\u2502';
+    const blank = '\u2502' + ' '.repeat(W - 2) + '\u2502';
     lines.push(top);
     lines.push(`\u2502${pad('  claude-slim report')}\u2502`);
     lines.push(blank);
@@ -94,6 +101,19 @@ export function formatReportBox(data) {
         lines.push(blank);
         lines.push(`\u2502${pad('  \u26a0 Token counts are approximations (bytes/4)')}\u2502`);
     }
+    if (data.unusedPlugins.count > 0) {
+        const n = data.unusedPlugins.count;
+        const pluginWord = n === 1 ? 'unused plugin' : 'unused plugins';
+        let hintText;
+        if (data.unusedPlugins.tokens > 0) {
+            hintText = `  ! ${n} ${pluginWord} (~${data.unusedPlugins.tokens.toLocaleString()} tok).`;
+        }
+        else {
+            hintText = `  ! ${n} ${pluginWord}. Run: claude-slim`;
+        }
+        lines.push(blank);
+        lines.push(`\u2502${pad(hintText)}\u2502`);
+    }
     lines.push(bot);
     // Breakdown table
     if (data.breakdown.length > 0) {
@@ -216,6 +236,14 @@ export function formatScanSummary(result) {
             lines.push(`  ${selected} ${i + 1}. \x1b[${color}m[${tierLabel}]\x1b[0m ${issue.type}: ${issue.name}${detail}${tokStr}${permanent}`);
         }
     }
+    // --- PLUGINS BREAKDOWN ---
+    if (result.pluginBreakdown && result.pluginBreakdown.length > 0) {
+        const totalInstalled = result.pluginBreakdown.length;
+        const totalEnabled = result.pluginBreakdown.filter((p) => p.status !== 'disabled').length;
+        lines.push(formatPluginsTable(result.pluginBreakdown, totalInstalled, totalEnabled));
+    }
     lines.push('');
     return lines.join('\n');
 }
+// Re-export for external callers (e.g. tests)
+export { formatPluginsTable };

package/dist/scanner/constants.d.ts

@@ -2,3 +2,6 @@ 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;
+export declare const DEFERRED_TOOL_OVERHEAD_TOKENS = 8;
+export declare const COMMAND_OVERHEAD_TOKENS = 10;
+export declare const MCP_SERVER_TOOLS_AVG = 10;

package/dist/scanner/constants.js

@@ -2,3 +2,11 @@ export const STALE_DAYS = 90;
 export const OVERSIZED_SKILL_BYTES = 10240;
 export const OVERSIZED_MEMORY_BYTES = 5120;
 export const SKILL_PROMPT_OVERHEAD_TOKENS = 30;
+// Calibrated from owner system prompt sample:
+// Deferred tools list ~1500 tokens / ~209 MCP tools ≈ 7.2 tok/tool → rounded up to 8.
+export const DEFERRED_TOOL_OVERHEAD_TOKENS = 8;
+// Estimated from slash-command list format in system prompt: ~10 tok/command.
+export const COMMAND_OVERHEAD_TOKENS = 10;
+// Average tools per MCP server (used when per-server tool count is unknown).
+// Most plugin MCP servers expose 5–15 tools; 10 is a reasonable midpoint.
+export const MCP_SERVER_TOOLS_AVG = 10;

package/dist/scanner/detectors.d.ts

@@ -1,6 +1,7 @@
 import type { SkillInfo, BrokenSymlink, MemoryFile, PluginInfo, Issue } from '../types.js';
 import type { TempCache } from './plugin-skills.js';
 import type { StaleProject } from './memory.js';
+import type { PluginSurfaces } from './plugin-surfaces.js';
 export interface DetectorContext {
     localSkills: SkillInfo[];
     pluginSkills: SkillInfo[];
@@ -14,6 +15,15 @@ export interface DetectorContext {
     recentSkillInvocations: Set<string>;
     sessionDataAvailable: boolean;
     lookbackDays: number;
+    pluginSurfaces: PluginSurfaces[];
+    enabledPlugins: Array<{
+        name: string;
+        marketplace: string;
+    }>;
+    recentMcpPrefixes: Set<string>;
+    recentCommands: Set<string>;
+    totalUserCallableInvocations: number;
+    sessionsInWindow: number;
 }
 export interface Detector {
     name: string;

package/dist/scanner/detectors.js

@@ -175,6 +175,49 @@ const unusedSkillDetector = {
         return issues;
     },
 };
+const unusedPluginDetector = {
+    name: 'unused_plugin',
+    detect({ pluginSurfaces, enabledPlugins, recentSkillInvocations, recentMcpPrefixes, recentCommands, totalUserCallableInvocations, sessionsInWindow, lookbackDays, }) {
+        // (a) Global suppression: too few sessions to draw a conclusion
+        if (sessionsInWindow < 3)
+            return [];
+        // (b) Global suppression: no user-callable activity — schema change suspected
+        if (totalUserCallableInvocations === 0)
+            return [];
+        const enabledNames = new Set(enabledPlugins.map((p) => p.name));
+        const issues = [];
+        for (const ps of pluginSurfaces) {
+            // Inner-join: only consider plugins reported as enabled (filters .git noise)
+            if (!enabledNames.has(ps.pluginName))
+                continue;
+            // (c) Per-plugin suppression: no user-callable surface (agent/hook only)
+            const userCallableCount = ps.skills.length + ps.mcpToolPrefixes.length + ps.commands.length;
+            if (userCallableCount === 0)
+                continue;
+            // (d) suppression was intended to skip recently-installed plugins by
+            // `installedAt` mtime, but dogfooding showed `claude plugin update` resets
+            // cache mtime indiscriminately, making install age unreliable. Dropped.
+            // Tier 3 (never auto-selected) lets users sanity-check any flagged plugin.
+            // Usage check: any skill/mcp/command from this plugin invoked?
+            const usedSkill = ps.skills.some((s) => recentSkillInvocations.has(s) ||
+                recentSkillInvocations.has(`${ps.pluginName}:${s}`));
+            const usedMcp = ps.mcpToolPrefixes.some((p) => recentMcpPrefixes.has(p));
+            const usedCmd = ps.commands.some((c) => recentCommands.has(c));
+            if (usedSkill || usedMcp || usedCmd)
+                continue;
+            issues.push({
+                type: 'unused_plugin',
+                tier: 3,
+                name: ps.pluginName,
+                marketplace: ps.marketplace,
+                detail: `not invoked in ${lookbackDays}d (${ps.marketplace})`,
+                tokens: 0,
+                path: ps.installDir,
+            });
+        }
+        return issues;
+    },
+};
 const disabledPluginDetector = {
     name: 'disabled_plugin',
     detect({ plugins, disabledPlugins }) {
@@ -206,6 +249,7 @@ export const detectors = [
     oversizedMemoryDetector,
     staleProjectDetector,
     unusedSkillDetector,
+    unusedPluginDetector,
     disabledPluginDetector,
 ];
 export function classifyIssues(ctx, registry = detectors) {

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

@@ -1,2 +1,9 @@
 export declare function parseDisabledPlugins(output: string): Set<string>;
 export declare function getDisabledPlugins(): Promise<Set<string>>;
+export interface InstalledPlugin {
+    name: string;
+    marketplace: string;
+    enabled: boolean;
+}
+export declare function parseInstalledPlugins(output: string): InstalledPlugin[];
+export declare function getInstalledPlugins(): Promise<InstalledPlugin[]>;

package/dist/scanner/disabled-plugins.js

@@ -24,3 +24,41 @@ export function parseDisabledPlugins(output) {
 export async function getDisabledPlugins() {
     return parseDisabledPlugins(await runCommand('claude', ['plugin', 'list']));
 }
+// Parse `claude plugin list` output into per-plugin entries. Unlike
+// parseDisabledPlugins (which collapses to marketplace name for cache-dir
+// matching), this preserves the full <plugin>@<marketplace> pair so callers
+// can match against plugin surface scanning by exact plugin name.
+export function parseInstalledPlugins(output) {
+    const plugins = [];
+    if (!output)
+        return plugins;
+    let current = null;
+    for (const line of output.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.startsWith('❯')) {
+            const full = trimmed.split('❯')[1]?.trim() || '';
+            const at = full.indexOf('@');
+            if (at > 0) {
+                current = { name: full.slice(0, at), marketplace: full.slice(at + 1) };
+            }
+            else if (full) {
+                current = { name: full, marketplace: full };
+            }
+            else {
+                current = null;
+            }
+        }
+        else if (current && trimmed.toLowerCase().includes('disabled')) {
+            plugins.push({ ...current, enabled: false });
+            current = null;
+        }
+        else if (current && trimmed.toLowerCase().includes('enabled')) {
+            plugins.push({ ...current, enabled: true });
+            current = null;
+        }
+    }
+    return plugins;
+}
+export async function getInstalledPlugins() {
+    return parseInstalledPlugins(await runCommand('claude', ['plugin', 'list']));
+}