claude-slim 2.7.3 → 2.8.1

package/README.md

@@ -3,12 +3,16 @@
 # claude-slim
 
 [![npm](https://img.shields.io/npm/v/claude-slim.svg)](https://www.npmjs.com/package/claude-slim)
+[![downloads](https://img.shields.io/npm/dm/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)
+[![node](https://img.shields.io/node/v/claude-slim.svg)](https://nodejs.org)
 [![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
@@ -26,17 +30,20 @@ Every Claude Code session auto-loads every skill, memory file, and plugin instru
   <img src="docs/demo.gif" alt="claude-slim cleanup: 11,442 tokens of overhead reduced to ~5,800 in 45 seconds" width="900" />
 </p>
 
-Where the bloat hides:
+Where the bloat hides — measured on one real install:
+
+| Source | What it costs | |
+|--------|:---:|---|
+| Skill listings | ~10,100 tokens | 256 skills × their `name: description` line |
+| Agent catalog | ~2,250 tokens | `~/.claude/agents/`, 12 agents |
+| CLAUDE.md | ~2,000 tokens | plugin instructions |
+| Deferred tools list | ~1,500 tokens | MCP tool schemas |
+| Slash commands | ~80 tokens | `~/.claude/commands/` |
+| Memory files | **0 – 63,500 tokens** | current project only — varies wildly per project |
 
-| Source | Typical overhead |
-|--------|:---:|
-| 60+ registered skills | ~3,000 tokens |
-| CLAUDE.md (plugin instructions) | ~5,000 tokens |
-| Memory files | ~2,500 tokens |
-| Deferred tools list | ~1,500 tokens |
-| **Total** | **~12,000 tokens** |
+Skill listings are the part people underestimate: each installed skill contributes one `- name: description` line to the system prompt, and those run anywhere from **30 to 509 tokens each**. Sixty terse skills and sixty verbose ones are not the same bill.
 
-That's slower responses. Hitting your usage cap faster. Paying for context you're not using.
+That's slower responses. Hitting your usage cap faster. Paying for context you're not using — on every turn, of every session.
 
 ---
 
@@ -67,6 +74,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 |
@@ -173,6 +181,7 @@ npx claude-slim report                   # Show savings from last clean
 
 - **`~/.claude/CLAUDE.md`** — your system instructions, read-only.
 - **`~/.claude/settings.json`** — MCP server config, hooks, and any other settings. Read-only.
+- **`~/.claude/agents/` and `~/.claude/commands/`** — measured and reported since v2.8, never moved or deleted. There is no restore path for them yet, and a destructive action without its undo isn't worth shipping.
 - **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.
@@ -188,9 +197,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)
 ```
 
@@ -209,17 +220,25 @@ From a real cleanup session:
 | Memory files | 15KB | 2KB | **-87%** |
 | **Est. token savings** | | **~4,300/session** | |
 
+### A note on the numbers
+
+claude-slim reports what a session in **this** directory pays. Memory is per-project — Claude Code loads `~/.claude/projects/<slug>/memory/` for the project you're in, not every project on disk — so running `scan` from two different repos will legitimately give you two different totals.
+
+Token counts come from [js-tiktoken](https://github.com/nicolo-ribaudo/js-tiktoken) against the actual file contents. The only estimates left are marked with `~`: MCP tool schemas (~8 tokens/tool) and skills whose frontmatter can't be parsed (~30 tokens). Everything else is measured.
+
 ---
 
-## v2.7.2 — What's new
+## v2.8.0 — What's new
 
-Correctness patch fixing three HIGH-severity issues from a post-2.7.1 review. No new features; no breaking changes.
+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.**
 
-- **Friendlier `unused_plugin` cleanup when the `claude` CLI is missing.** Users running claude-slim outside a Claude Code install used to see raw `spawn claude ENOENT` — one row per selected plugin. The cleaner now probes the CLI once up front via `isClaudeCliAvailable()`; failing items become `skipped` (not `errored`), and a single grouped warning points at the manual `claude plugin disable <name>` workaround.
-- **Nested-skill scanner now covers 3-deep layouts.** The prior 2-level walk silently missed `skills/<org>/<group>/<skill>/SKILL.md` — token totals under-reported and `unused_skill` could never flag them. Replaced with a bounded recursive walk (`MAX_SKILL_DEPTH = 3`) that stops descending once a `SKILL.md` is found, so nested docs under a declared skill don't become phantom duplicates.
-- **`scan --json` output contract locked in.** New test spies on `console.log` / `console.info` / `console.warn` during the full scan pipeline (both minimal and rich fixtures — session logs, plugin cache, memory, CLAUDE.md) and fails if any fires. No stray writes exist today; the invariant is now enforced so a future refactor can't silently break `claude-slim scan --json | jq`.
+- **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.
 
-Tests: 190 → 206 (+16).
+Tests: 206 → 241 (+35).
 
 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;
@@ -11,13 +11,18 @@ function getCachePath() {
 let cache = { version: 1, entries: {} };
 let cacheDirty = false;
 export async function initTokenizer() {
-    try {
-        // cl100k_base is closest to Claude's tokenizer (gpt-4o uses o200k_base which undercounts by ~15%)
-        const { getEncoding } = await import('js-tiktoken');
-        encoder = getEncoding('cl100k_base');
-    }
-    catch {
-        useFallback = true;
+    // Building the cl100k_base encoder parses a large rank table — hundreds of
+    // milliseconds, and far more under CPU contention. It is immutable once
+    // built, so reuse it across calls. Only the cache is per-init state.
+    if (encoder === null && !useFallback) {
+        try {
+            // cl100k_base is closest to Claude's tokenizer (gpt-4o uses o200k_base which undercounts by ~15%)
+            const { getEncoding } = await import('js-tiktoken');
+            encoder = getEncoding('cl100k_base');
+        }
+        catch {
+            useFallback = true;
+        }
     }
     // Reset in-memory state so repeated initTokenizer() calls (e.g. across
     // test cases) don't bleed cache entries from a prior invocation.
@@ -51,9 +56,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.3",
-  "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.1",
+  "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"
   }
 }