claude-slim 2.7.2 → 2.8.0

package/README.md

@@ -6,9 +6,11 @@
 [![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."**
+**Your Claude Code session burns thousands of tokens before you even say "hello."**
 
-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.
+Every session auto-loads every skill, agent, slash command, 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 on every single turn. claude-slim measures that startup overhead and removes what you don't need.
+
+No proxy, no compression, no changes to how Claude Code talks to the API — it reads `~/.claude/`, tells you what each skill and plugin actually costs, and moves the dead weight aside reversibly.
 
 ```
 /claude-slim
@@ -67,6 +69,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)** |
+| Agents & commands | `~/.claude/agents/` and `~/.claude/commands/` — measured and reported, never modified |
 | **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 |
@@ -188,9 +191,11 @@ claude-slim scans these locations. No plugin-specific logic — pure filesystem
 ```
 ~/.claude/
 ├── skills/                  ← user-installed skills
-├── plugins/cache/           ← plugin skills
+├── plugins/cache/           ← plugin skills, agents, commands, MCP servers
+├── agents/                  ← user agents (measured, read-only)
+├── commands/                ← user slash commands (measured, read-only)
 ├── CLAUDE.md                ← system instructions (read-only)
-├── projects/*/memory/       ← auto-memory files
+├── projects/*/memory/       ← auto-memory files (current project counts toward startup)
 └── settings.json            ← MCP server count (read-only)
 ```
 
@@ -211,72 +216,19 @@ From a real cleanup session:
 
 ---
 
-## v2.7.1 — What's new
-
-Correctness patch cleaning up seven bugs found in post-2.7 review. No new features; no breaking changes.
-
-- **`unused_plugin` savings always showed 0.** The detector emitted `tokens: 0` for every flagged plugin, so both the dry-run summary and the final report box under-counted savings for what is typically the largest cleanup target. Cost is now threaded through `DetectorContext` and the detector uses the real per-plugin value.
-- **`duplicate` detector could disable namespaced local skills.** A `baseName` fallback flagged `org/ship` as a duplicate of a bare plugin `ship`, even though namespaced local skills are addressable independently. Only exact-name matches are flagged now.
-- **`stale_project` restore was scoped to all of `~/.claude/`.** A tampered manifest could redirect a project-memory backup into `~/.claude/skills/` and clobber an unrelated asset. Restores are now type-scoped — `stale_project` targets must live under `~/.claude/projects/`, skill restores under `~/.claude/skills/`.
-- **Non-interactive `claude-slim clean` refuses to auto-apply.** Prior behavior silently auto-selected Tier 1 in non-TTY without `--auto`/`--dry-run`, surprising users running from scripts. It now prints a warning and exits with status 1; opt in explicitly with `--auto` or `--dry-run`.
-- **`--lookback-days 0` / `--sessions-per-day 0` are respected.** `parseInt(x, 10) || N` was silently upgrading explicit `0` to the default. Replaced with a `parseNonNegativeInt` helper.
-- **`claude-slim report` recognizes zero-token cleanups.** Runs that only removed `broken_symlink` or `temp_cache` entries were being reported as "no previous cleanup"; every manifest entry now counts.
-- **Session parser regex hardened.** `extractCommandsFromTranscript` uses `String.matchAll` instead of a manual `lastIndex`-resetting loop — one fewer footgun for future refactors.
-
-Tests: 188 → 190 (+2 regression cases for the token-propagation fix).
-
-## 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.
-- **Clearer safety wording** — Skills and project memory are reversible moves into `~/.claude/skills.disabled/`; broken symlink files and failed-install `temp_local_*` caches are permanent cleanup targets and are labeled before selection.
-- **Pinned development Node version** — `.nvmrc` and `.node-version` pin contributors to Node 22.12.0, matching the current Vitest/Vite/Rolldown patch-floor requirements.
-
-## 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.8.0 — What's new
 
-## v2.2 — What's new
+Accuracy release. Three reported numbers were wrong; the largest was wrong by an order of magnitude. **If your startup estimate drops sharply after upgrading, the old number was the inaccurate one.**
 
-- **Atomic `stale_project` clean/restore** — Single directory `rename()` instead of per-file loop. No more partial-failure state if the operation is interrupted.
-- **Clear collision errors** — Cleaning a project whose backup already exists (or restoring onto an existing directory) now fails with an actionable message instead of a cryptic OS error.
-- **Manifest schema v2** — Single JSON file (`manifest.json`) containing only currently-disabled entries. Restore removes the entry entirely, so the manifest stays bounded across many clean/restore cycles.
-- **Automatic migration from v1** — Existing legacy manifests (`.claude-slim-manifest.jsonl`) are auto-migrated on first read; the original is preserved as `.jsonl.bak` for safety.
-- **Crash-safe manifest writes** — Write-to-tmp-then-rename pattern prevents partial-write corruption on power loss or SIGKILL.
-- **Expanded test coverage** — 66 tests (was 35). New round-trip tests per issue type: `broken_symlink`, `template`, `duplicate`, `skill_dup`, `oversized_skill`, `temp_cache`, `stale_project`. Plus manifest migration + bounded-growth cycle tests.
+- **Startup estimate no longer sums memory across every project on disk.** Claude Code loads `~/.claude/projects/<slug>/memory/` for the project you're in — not the other 40 project directories in your `~/.claude`. The old total scaled with how many projects you'd ever opened: on the dev machine it reported **116,259 tokens where the real per-session cost was 14,399**. Now scoped to the current project, with the cross-project total still shown and labelled as not a per-session cost.
+- **Skill listing cost is measured, not assumed.** Each skill adds a `- <name>: <description>` line to the system prompt. The flat 30-tokens-per-skill estimate stood in for all of them; measured across 68 installed skills the real spread is **30 → 509 tokens (mean 51)**. The per-plugin cost gradient can now tell five terse skills apart from five verbose ones.
+- **`~/.claude/agents/` and `~/.claude/commands/` are now scanned.** Previously invisible despite loading into every session — 12 agents worth ~2,254 tokens on the dev machine. Reported only; never moved or deleted, because there's no restore path for them yet.
+- **Fixed: plugin manifests were stuck at 2.7.0 for three releases**, so `claude plugin install` advertised a stale version. CI now fails on version drift.
+- **Fixed: the token cache grew without bound** — 355 of 776 entries (46%) pointed at deleted files. `flushCache()` now prunes them.
 
-## v2.0 — What's new
+Tests: 206 → 241 (+35).
 
-- **TypeScript CLI** — Rewritten from bash. Faster, more accurate, extensible.
-- **Accurate token counting** — [js-tiktoken](https://github.com/nicolo-ribaudo/js-tiktoken) with `cl100k_base` encoding.
-- **Savings report box** — Visual before/after with breakdown table and monthly savings estimate.
-- **`--dry-run`** — Preview changes without making them.
-- **`--json`** — Machine-readable output for automation.
-- **Token cache** — Instant repeat scans.
-- **Standalone CLI** — `npx claude-slim` works outside Claude Code.
-- **`--auto`** — Non-interactive cleanup for CI/scripts (Tier 1 only).
-- **Disabled plugin detection** — Finds plugins you disabled but didn't uninstall.
-- **Stale project detection** — Flags project memory untouched for 90+ days.
-- **CLAUDE.md section breakdown** — See which plugin instructions cost the most tokens.
-- **Plugin status** — Shows enabled/disabled status for each plugin.
-- **Non-TTY support** — Auto-selects Tier 1 when stdin is piped.
-- **Unit tests** — Vitest-based.
+For older release notes, see [CHANGELOG.md](CHANGELOG.md).
 
 ---
 

package/dist/cli.js

@@ -201,6 +201,10 @@ program
                 path: e.from,
                 sizeBytes: 0,
                 tokens: e.tokenCount || 0,
+                // The file is gone, so its real listing cost is unrecoverable. Fall
+                // back to the flat estimate — the same one `totalBefore` above uses,
+                // keeping the reconstructed before-state internally consistent.
+                listingTokens: SKILL_PROMPT_OVERHEAD_TOKENS,
                 source: 'local',
             })),
         ],

package/dist/paths.d.ts

@@ -3,6 +3,15 @@ export declare function getSkillsDir(): string;
 export declare function getPluginsDir(): string;
 export declare function getProjectsDir(): string;
 export declare function getDisabledDir(): string;
+/**
+ * Claude Code stores per-project state under `~/.claude/projects/<slug>/`,
+ * where the slug is the absolute project path with every `/` replaced by `-`
+ * (e.g. `/Users/me/app` → `-Users-me-app`).
+ *
+ * Only the current project's `memory/` is loaded into a session — which is why
+ * the startup estimate must not sum memory across every project on disk.
+ */
+export declare function getCurrentProjectSlug(cwd?: string): string;
 export declare function getManifestPath(): string;
 export declare function getLegacyManifestPath(): string;
 export declare function assertInsideClaudeDir(p: string): void;

package/dist/paths.js

@@ -15,6 +15,17 @@ export function getProjectsDir() {
 export function getDisabledDir() {
     return join(getClaudeDir(), 'skills.disabled');
 }
+/**
+ * Claude Code stores per-project state under `~/.claude/projects/<slug>/`,
+ * where the slug is the absolute project path with every `/` replaced by `-`
+ * (e.g. `/Users/me/app` → `-Users-me-app`).
+ *
+ * Only the current project's `memory/` is loaded into a session — which is why
+ * the startup estimate must not sum memory across every project on disk.
+ */
+export function getCurrentProjectSlug(cwd = process.cwd()) {
+    return resolve(cwd).replace(/\//g, '-');
+}
 export function getManifestPath() {
     return join(getDisabledDir(), 'manifest.json');
 }

package/dist/report.js

@@ -181,7 +181,6 @@ export function formatScanSummary(result) {
     // --- MEMORY FILES ---
     lines.push('');
     const memTotal = result.memoryFiles.reduce((s, m) => s + m.sizeBytes, 0);
-    const memTokTotal = result.memoryFiles.reduce((s, m) => s + m.tokens, 0);
     lines.push(`\x1b[1m  MEMORY FILES\x1b[0m (${result.memoryFiles.length} files, ${(memTotal / 1024).toFixed(1)}KB)`);
     const sortedMem = [...result.memoryFiles].sort((a, b) => b.sizeBytes - a.sizeBytes);
     for (const mem of sortedMem) {
@@ -194,7 +193,16 @@ export function formatScanSummary(result) {
             project = rest ? '~' + rest : '~';
         }
         const label = `${project}/${mem.name}`;
-        lines.push(`    ${label.padEnd(52)} ${kb.padStart(6)}KB  ${tok.padStart(7)} tok`);
+        // Mark the only project whose memory this session would actually load.
+        const active = mem.project === result.currentProjectSlug ? ' \x1b[32m←\x1b[0m' : '';
+        lines.push(`    ${label.padEnd(52)} ${kb.padStart(6)}KB  ${tok.padStart(7)} tok${active}`);
+    }
+    if (result.memoryFiles.length > 0) {
+        lines.push('');
+        lines.push(`    \x1b[32m←\x1b[0m loaded in this project: ` +
+            `${result.currentProjectMemoryTokens.toLocaleString()} tok  ` +
+            `\x1b[90m(${result.allProjectsMemoryTokens.toLocaleString()} tok across all projects, ` +
+            `not a per-session cost)\x1b[0m`);
     }
     // --- MCP SERVERS ---
     lines.push('');
@@ -207,6 +215,26 @@ export function formatScanSummary(result) {
     else {
         lines.push(`\x1b[1m  MCP SERVERS\x1b[0m: ${result.mcpServers}`);
     }
+    // --- USER AGENTS & COMMANDS ---
+    // Read-only in v2.8: these are measured and reported, but never moved or
+    // deleted. There is no restore path for ~/.claude/agents yet, and shipping a
+    // destructive action without its undo would break the tool's core promise.
+    const agentTokens = result.userAgents.reduce((s, a) => s + a.listingTokens, 0);
+    const commandTokens = result.userCommands.reduce((s, c) => s + c.listingTokens, 0);
+    if (result.userAgents.length > 0 || result.userCommands.length > 0) {
+        lines.push('');
+        lines.push(`\x1b[1m  AGENTS & COMMANDS\x1b[0m ` +
+            `(${result.userAgents.length} agents, ${result.userCommands.length} commands)`);
+        if (result.userAgents.length > 0) {
+            lines.push(`    ~/.claude/agents/`.padEnd(56) +
+                `${agentTokens.toLocaleString().padStart(7)} tok`);
+        }
+        if (result.userCommands.length > 0) {
+            lines.push(`    ~/.claude/commands/`.padEnd(56) +
+                `${commandTokens.toLocaleString().padStart(7)} tok`);
+        }
+        lines.push(`    \x1b[90mreported only — not touched by clean\x1b[0m`);
+    }
     // --- SUMMARY ---
     lines.push('');
     lines.push(`\x1b[1m  ESTIMATED OVERHEAD\x1b[0m: ~${result.totalTokensBefore.toLocaleString()} tokens at session start`);

package/dist/scanner/index.js

@@ -5,7 +5,7 @@
 // src/__tests__/scan-stdout-invariant.test.ts.
 import { join } from 'node:path';
 import { countTokensCached } from '../tokenizer.js';
-import { getClaudeDir } from '../paths.js';
+import { getClaudeDir, getCurrentProjectSlug } from '../paths.js';
 import { safeReadFile } from './fs-walk.js';
 import { scanLocalSkills } from './local-skills.js';
 import { scanPluginSkills } from './plugin-skills.js';
@@ -18,17 +18,18 @@ import { classifyIssues } from './detectors.js';
 import { scanPluginSurfaces } from './plugin-surfaces.js';
 import { computePluginBreakdown } from './plugin-breakdown.js';
 import { computePluginCosts } from './plugin-cost.js';
-import { SKILL_PROMPT_OVERHEAD_TOKENS } from './constants.js';
+import { scanUserSurfaces } from './user-surfaces.js';
 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([
+    const [{ skills: localSkills, brokenSymlinks, contents }, { skills: pluginSkills, plugins, tempCaches }, { memoryFiles, staleProjects }, mcp, disabledPlugins, sessionUsage, userSurfaces,] = await Promise.all([
         scanLocalSkills(),
         scanPluginSkills(),
         scanMemoryFiles(),
         scanMcpServers(),
         getDisabledPlugins(),
         scanSessionUsage(lookbackDays),
+        scanUserSurfaces(),
     ]);
     const pluginSurfaces = scanPluginSurfaces();
     // Annotate plugin status
@@ -84,10 +85,28 @@ export async function scan(opts = {}) {
         sessionsInWindow: sessionUsage.sessionsInWindow,
         claudeMdSections,
     });
-    // 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;
+    // Estimate total tokens at startup. Skill/agent/command listing costs are
+    // measured from each file's frontmatter description rather than assumed
+    // (see scanner/skill-listing.ts) — the real spread is 30–500+ tokens apiece.
+    const sumListing = (entries) => entries.reduce((sum, e) => sum + e.listingTokens, 0);
+    const skillListingTokens = sumListing(localSkills) + sumListing(pluginSkills);
+    const agentListingTokens = sumListing(userSurfaces.agents);
+    const commandListingTokens = sumListing(userSurfaces.commands);
+    // Memory is per-project: a session loads ~/.claude/projects/<slug>/memory/
+    // for the project it is running in, and nothing from the other projects on
+    // disk. Summing all of them (pre-2.8 behaviour) inflated the startup estimate
+    // by a factor of however many projects the user had — 100k+ tokens on a busy
+    // machine, for a number labelled "tokens at session start".
+    const currentProjectSlug = getCurrentProjectSlug();
+    const currentProjectMemoryTokens = memoryFiles
+        .filter((m) => m.project === currentProjectSlug)
+        .reduce((sum, m) => sum + m.tokens, 0);
+    const allProjectsMemoryTokens = memoryFiles.reduce((sum, m) => sum + m.tokens, 0);
+    const totalTokensBefore = skillListingTokens +
+        agentListingTokens +
+        commandListingTokens +
+        claudeMdTokens +
+        currentProjectMemoryTokens;
     return {
         localSkills,
         pluginSkills,
@@ -102,5 +121,10 @@ export async function scan(opts = {}) {
         issues,
         totalTokensBefore,
         pluginBreakdown,
+        userAgents: userSurfaces.agents,
+        userCommands: userSurfaces.commands,
+        currentProjectSlug,
+        currentProjectMemoryTokens,
+        allProjectsMemoryTokens,
     };
 }

package/dist/scanner/local-skills.js

@@ -3,6 +3,7 @@ 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';
+import { listingTokensFromContent } from './skill-listing.js';
 export function dedupeBySymlink(candidates) {
     const seen = new Map();
     for (const { skill, realMdPath } of candidates) {
@@ -57,6 +58,7 @@ export async function scanLocalSkills() {
                     path: dirPath,
                     sizeBytes: Buffer.byteLength(content),
                     tokens,
+                    listingTokens: listingTokensFromContent(displayName, content),
                     source: 'local',
                 },
                 realMdPath,

package/dist/scanner/plugin-cost.d.ts

@@ -4,7 +4,7 @@ export interface PluginCostBreakdown {
     marketplace: string;
     /** Tokens from the matching CLAUDE.md section (0 if no match). */
     claudeMdTokens: number;
-    /** SKILL_PROMPT_OVERHEAD_TOKENS × skills.length */
+    /** Measured sum of each skill's `- <name>: <description>` listing line. */
     skillTokens: number;
     /** DEFERRED_TOOL_OVERHEAD_TOKENS × MCP_SERVER_TOOLS_AVG × mcpServerKeys.length */
     mcpToolTokens: number;

package/dist/scanner/plugin-cost.js

@@ -1,4 +1,4 @@
-import { SKILL_PROMPT_OVERHEAD_TOKENS, DEFERRED_TOOL_OVERHEAD_TOKENS, COMMAND_OVERHEAD_TOKENS, MCP_SERVER_TOOLS_AVG, } from './constants.js';
+import { DEFERRED_TOOL_OVERHEAD_TOKENS, COMMAND_OVERHEAD_TOKENS, MCP_SERVER_TOOLS_AVG, } from './constants.js';
 /**
  * Find a CLAUDE.md section whose name contains the plugin name as a substring
  * (case-insensitive). Returns the first match or null.
@@ -18,7 +18,7 @@ export function computePluginCosts(surfaces, claudeMdSections) {
     return surfaces.map((s) => {
         const matched = matchSection(s.pluginName, claudeMdSections);
         const claudeMdTokens = matched?.tokens ?? 0;
-        const skillTokens = SKILL_PROMPT_OVERHEAD_TOKENS * s.skills.length;
+        const skillTokens = s.skillListingTokens;
         const mcpToolTokens = DEFERRED_TOOL_OVERHEAD_TOKENS * MCP_SERVER_TOOLS_AVG * s.mcpServerKeys.length;
         const commandTokens = COMMAND_OVERHEAD_TOKENS * s.commands.length;
         const totalEstimatedTokens = claudeMdTokens + skillTokens + mcpToolTokens + commandTokens;

package/dist/scanner/plugin-skills.js

@@ -2,6 +2,7 @@ import { join } from 'node:path';
 import { countTokensCached } from '../tokenizer.js';
 import { getPluginsDir } from '../paths.js';
 import { safeReadFile, safeReaddir, isDirectory, getDirSize } from './fs-walk.js';
+import { listingTokensFromContent } from './skill-listing.js';
 export async function scanPluginSkills() {
     const skills = [];
     const plugins = [];
@@ -40,6 +41,7 @@ export async function scanPluginSkills() {
                                 path: skillPath,
                                 sizeBytes: Buffer.byteLength(content),
                                 tokens: countTokensCached(content, skillMd),
+                                listingTokens: listingTokensFromContent(skillDir, content),
                                 source: 'plugin',
                                 pluginName,
                             });

package/dist/scanner/plugin-surfaces.d.ts

@@ -5,6 +5,7 @@ export interface PluginSurfaces {
     installDir: string;
     installedAt: number;
     skills: string[];
+    skillListingTokens: number;
     mcpServerKeys: string[];
     mcpToolPrefixes: string[];
     commands: string[];

package/dist/scanner/plugin-surfaces.js

@@ -2,6 +2,8 @@ import { join } from 'node:path';
 import { statSync } from 'node:fs';
 import { readFileSync, readdirSync } from 'node:fs';
 import { getPluginsDir } from '../paths.js';
+import { listingTokensFromContent } from './skill-listing.js';
+import { SKILL_PROMPT_OVERHEAD_TOKENS } from './constants.js';
 function safeReaddir(p) {
     try {
         return readdirSync(p);
@@ -49,19 +51,29 @@ function parseMcpServerKeys(installDir) {
 function scanSkills(installDir) {
     const skillsDir = join(installDir, 'skills');
     if (!isDir(skillsDir))
-        return [];
+        return { names: [], listingTokens: 0 };
     const names = [];
+    let listingTokens = 0;
     for (const entry of safeReaddir(skillsDir)) {
         const skillDir = join(skillsDir, entry);
         if (!isDir(skillDir))
             continue;
         const upper = join(skillDir, 'SKILL.md');
         const lower = join(skillDir, 'skill.md');
-        if (isFile(upper) || isFile(lower)) {
-            names.push(entry);
+        const present = isFile(upper) ? upper : isFile(lower) ? lower : null;
+        if (present === null)
+            continue;
+        names.push(entry);
+        let content = '';
+        try {
+            content = readFileSync(present, 'utf-8');
         }
+        catch { /* unreadable */ }
+        listingTokens += content
+            ? listingTokensFromContent(entry, content)
+            : SKILL_PROMPT_OVERHEAD_TOKENS;
     }
-    return names;
+    return { names, listingTokens };
 }
 function scanCommands(installDir) {
     const commandsDir = join(installDir, 'commands');
@@ -103,7 +115,7 @@ export function scanPluginSurfaces() {
                     continue;
                 const dirStat = safeStat(installDir);
                 const installedAt = dirStat ? Number(dirStat.mtimeMs) : 0;
-                const skills = scanSkills(installDir);
+                const { names: skills, listingTokens: skillListingTokens } = scanSkills(installDir);
                 const mcpServerKeys = parseMcpServerKeys(installDir);
                 const mcpToolPrefixes = mcpServerKeys.map((key) => `plugin_${pluginName}_${key}`);
                 const commands = scanCommands(installDir);
@@ -116,6 +128,7 @@ export function scanPluginSurfaces() {
                     installDir,
                     installedAt,
                     skills,
+                    skillListingTokens,
                     mcpServerKeys,
                     mcpToolPrefixes,
                     commands,

package/dist/scanner/skill-listing.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Extract the `description` value from a SKILL.md (or agent .md) frontmatter
+ * block. Returns null when there is no frontmatter or no description key —
+ * callers fall back to {@link SKILL_PROMPT_OVERHEAD_TOKENS}.
+ */
+export declare function parseFrontmatterDescription(content: string): string | null;
+/**
+ * Token cost of one entry in the system prompt's skill listing.
+ *
+ * Falls back to the flat {@link SKILL_PROMPT_OVERHEAD_TOKENS} estimate when the
+ * description is missing or unreadable, so a malformed SKILL.md degrades to the
+ * pre-2.8 behaviour rather than reporting zero.
+ */
+export declare function listingTokens(name: string, description: string | null): number;
+/** Convenience wrapper: parse a raw SKILL.md and return its listing cost. */
+export declare function listingTokensFromContent(name: string, content: string): number;

package/dist/scanner/skill-listing.js

@@ -0,0 +1,66 @@
+import { countTokens } from '../tokenizer.js';
+import { SKILL_PROMPT_OVERHEAD_TOKENS } from './constants.js';
+// Claude Code renders each available skill into the system prompt as one line:
+//   `- <name>: <description>`
+// The description comes from the SKILL.md YAML frontmatter and is reproduced
+// verbatim, so its real length — not a flat per-skill constant — is what the
+// session actually pays for. Measured across 68 installed skills the spread is
+// 30 → 509 tokens (mean 51), which a fixed estimate cannot represent.
+const LISTING_PREFIX = '- ';
+const LISTING_SEPARATOR = ': ';
+// Frontmatter block at the very top of the file: `---\n<yaml>\n---`.
+const FRONTMATTER_PATTERN = /^---\r?\n([\s\S]*?)\r?\n---/;
+// `description:` up to the next top-level key. YAML folded/literal blocks and
+// plain multi-line values both indent their continuation lines, so "next line
+// that starts at column 0 with `key:`" is the terminator.
+//
+// Deliberately NOT /m: with the multiline flag `$` matches end-of-line, which
+// would terminate the capture at the first newline and silently truncate every
+// wrapped description to its first line.
+const DESCRIPTION_PATTERN = /(?:^|\n)description:[ \t]*([\s\S]*?)(?=\r?\n[A-Za-z_][\w-]*:|$)/;
+/**
+ * Extract the `description` value from a SKILL.md (or agent .md) frontmatter
+ * block. Returns null when there is no frontmatter or no description key —
+ * callers fall back to {@link SKILL_PROMPT_OVERHEAD_TOKENS}.
+ */
+export function parseFrontmatterDescription(content) {
+    const fm = FRONTMATTER_PATTERN.exec(content);
+    if (!fm)
+        return null;
+    const match = DESCRIPTION_PATTERN.exec(fm[1]);
+    if (!match)
+        return null;
+    const raw = match[1]
+        // Drop a leading YAML block scalar indicator (`|`, `>`, `|-`, `>-`, …).
+        .replace(/^[|>][+-]?\d*[ \t]*\r?\n/, '')
+        // Collapse the indentation + wrapping that YAML uses for long values;
+        // the system prompt renders them as a single line.
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .join(' ')
+        .trim();
+    if (!raw)
+        return null;
+    // Strip surrounding quotes if the value was quoted.
+    const unquoted = (raw.startsWith('"') && raw.endsWith('"')) ||
+        (raw.startsWith("'") && raw.endsWith("'"))
+        ? raw.slice(1, -1)
+        : raw;
+    return unquoted.trim() || null;
+}
+/**
+ * Token cost of one entry in the system prompt's skill listing.
+ *
+ * Falls back to the flat {@link SKILL_PROMPT_OVERHEAD_TOKENS} estimate when the
+ * description is missing or unreadable, so a malformed SKILL.md degrades to the
+ * pre-2.8 behaviour rather than reporting zero.
+ */
+export function listingTokens(name, description) {
+    if (description === null)
+        return SKILL_PROMPT_OVERHEAD_TOKENS;
+    return countTokens(LISTING_PREFIX + name + LISTING_SEPARATOR + description);
+}
+/** Convenience wrapper: parse a raw SKILL.md and return its listing cost. */
+export function listingTokensFromContent(name, content) {
+    return listingTokens(name, parseFrontmatterDescription(content));
+}

package/dist/scanner/user-surfaces.d.ts

@@ -0,0 +1,16 @@
+export interface UserSurfaceEntry {
+    name: string;
+    path: string;
+    sizeBytes: number;
+    /** Full file body — what the agent/command costs once invoked. */
+    tokens: number;
+    /** What it costs at startup by merely existing. */
+    listingTokens: number;
+}
+export interface UserSurfacesResult {
+    agents: UserSurfaceEntry[];
+    commands: UserSurfaceEntry[];
+}
+export declare function getUserAgentsDir(): string;
+export declare function getUserCommandsDir(): string;
+export declare function scanUserSurfaces(): Promise<UserSurfacesResult>;

package/dist/scanner/user-surfaces.js

@@ -0,0 +1,59 @@
+import { join } from 'node:path';
+import { getClaudeDir } from '../paths.js';
+import { countTokensCached } from '../tokenizer.js';
+import { safeReadFile, safeReaddir, isBrokenSymlink } from './fs-walk.js';
+import { listingTokens, parseFrontmatterDescription } from './skill-listing.js';
+import { COMMAND_OVERHEAD_TOKENS } from './constants.js';
+export function getUserAgentsDir() {
+    return join(getClaudeDir(), 'agents');
+}
+export function getUserCommandsDir() {
+    return join(getClaudeDir(), 'commands');
+}
+/** Agents render exactly like skills: `- <name>: <description>`. */
+function agentListingCost(name, content) {
+    return listingTokens(name, parseFrontmatterDescription(content));
+}
+/**
+ * Commands without frontmatter appear as a bare name in the listing, which is
+ * what COMMAND_OVERHEAD_TOKENS already estimates for plugin commands. With a
+ * description they cost the same as a skill line.
+ */
+function commandListingCost(name, content) {
+    const description = parseFrontmatterDescription(content);
+    if (description === null)
+        return COMMAND_OVERHEAD_TOKENS;
+    return listingTokens(name, description);
+}
+async function scanMarkdownDir(dir, listingCost) {
+    const entries = await safeReaddir(dir);
+    const results = await Promise.all(entries.map(async (entry) => {
+        if (!entry.endsWith('.md'))
+            return null;
+        const path = join(dir, entry);
+        // Symlinked agents are common (vendored packs link into ~/.claude/agents).
+        // A dangling link contributes nothing to the prompt — skip it rather than
+        // counting a phantom entry.
+        if (await isBrokenSymlink(path))
+            return null;
+        const content = await safeReadFile(path);
+        if (content === null)
+            return null;
+        const name = entry.slice(0, -3);
+        return {
+            name,
+            path,
+            sizeBytes: Buffer.byteLength(content),
+            tokens: countTokensCached(content, path),
+            listingTokens: listingCost(name, content),
+        };
+    }));
+    return results.filter((r) => r !== null);
+}
+export async function scanUserSurfaces() {
+    const [agents, commands] = await Promise.all([
+        scanMarkdownDir(getUserAgentsDir(), agentListingCost),
+        scanMarkdownDir(getUserCommandsDir(), commandListingCost),
+    ]);
+    return { agents, commands };
+}

package/dist/tokenizer.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { readFile, writeFile, mkdir, rename } from 'node:fs/promises';
+import { readFile, writeFile, mkdir, rename, access } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { getClaudeDir } from './paths.js';
 let encoder = null;
@@ -51,9 +51,35 @@ export function countTokensCached(text, filePath) {
     cacheDirty = true;
     return tokens;
 }
+/**
+ * Drop cache entries whose source file no longer exists.
+ *
+ * Skills get uninstalled, plugins get removed, sessions get rotated — but the
+ * entry keyed by that path stayed forever, so the cache grew without bound. A
+ * path that is gone can never produce a hit again, which makes existence the
+ * safe pruning predicate: it cannot evict an entry that is still reachable.
+ * (Measured on a real install before this fix: 355 of 776 entries were dead.)
+ */
+async function pruneMissingEntries() {
+    const paths = Object.keys(cache.entries);
+    const alive = await Promise.all(paths.map(async (p) => {
+        try {
+            await access(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }));
+    for (let i = 0; i < paths.length; i++) {
+        if (!alive[i])
+            delete cache.entries[paths[i]];
+    }
+}
 export async function flushCache() {
     if (!cacheDirty)
         return;
+    await pruneMissingEntries();
     const target = getCachePath();
     const tmp = target + '.tmp';
     try {

package/dist/types.d.ts

@@ -1,8 +1,17 @@
+import type { UserSurfaceEntry } from './scanner/user-surfaces.js';
+export type { UserSurfaceEntry };
 export interface SkillInfo {
     name: string;
     path: string;
     sizeBytes: number;
+    /** Full SKILL.md body tokens — what the skill costs once invoked. */
     tokens: number;
+    /**
+     * Tokens this skill adds to the system prompt just by being installed
+     * (its `- <name>: <description>` listing line). Measured from the
+     * frontmatter description; see scanner/skill-listing.ts.
+     */
+    listingTokens: number;
     source: 'local' | 'plugin';
     pluginName?: string;
 }
@@ -63,6 +72,16 @@ export interface ScanResult {
     issues: Issue[];
     totalTokensBefore: number;
     pluginBreakdown: PluginBreakdown[];
+    /** ~/.claude/agents/*.md — loaded into the system prompt as the agent catalog. */
+    userAgents: UserSurfaceEntry[];
+    /** ~/.claude/commands/*.md — loaded as the slash-command listing. */
+    userCommands: UserSurfaceEntry[];
+    /** Project slug (cwd with `/` → `-`) whose memory a session here would load. */
+    currentProjectSlug: string;
+    /** Memory tokens actually loaded at startup — current project only. */
+    currentProjectMemoryTokens: number;
+    /** Memory tokens across every project on disk. Not a per-session cost. */
+    allProjectsMemoryTokens: number;
 }
 export interface ManifestEntry {
     date: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-slim",
-  "version": "2.7.2",
-  "description": "Cut Claude Code startup token overhead — non-destructive scan, tiered proposals, one-command restore. Finds unused skills, duplicate registrations, stale memory, and heavyweight plugins in ~/.claude/.",
+  "version": "2.8.0",
+  "description": "Audit and shrink your Claude Code startup context. Measures what every skill, plugin, agent, command, and memory file costs in the system prompt, then reversibly disables the dead weight. Non-destructive scan, tiered proposals, one-command restore — no proxy, no compression.",
   "type": "module",
   "bin": {
     "claude-slim": "./dist/cli.js"
@@ -16,9 +16,10 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "test": "vitest run",
+    "check:versions": "node scripts/check-version-sync.mjs",
     "test:watch": "vitest",
     "demo": "npm run build && bash scripts/demo/fixture.sh && vhs scripts/demo/demo.tape",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run check:versions && npm run build"
   },
   "keywords": [
     "claude",
@@ -35,7 +36,13 @@
     "plugin",
     "plugin-cleanup",
     "cli",
-    "developer-experience"
+    "developer-experience",
+    "context-engineering",
+    "context-window",
+    "agent-skills",
+    "claude-code-plugin",
+    "usage-limits",
+    "llm-tools"
   ],
   "author": "iops-leo",
   "license": "MIT",
@@ -51,13 +58,13 @@
     "node": ">=20"
   },
   "dependencies": {
-    "commander": "^13.0.0",
+    "commander": "^14.0.3",
     "js-tiktoken": "^1.0.18"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0",
+    "@types/node": "^22.20.1",
     "tmp-promise": "^3.0.3",
-    "typescript": "^5.7.0",
-    "vitest": "^4.1.4"
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.10"
   }
 }