claude-slim 2.9.0 → 2.10.0

package/README.md

@@ -161,6 +161,7 @@ npx claude-slim clean --dry-run          # See what would happen (no changes)
 npx claude-slim clean --auto             # Non-interactive, Tier 1 only (CI/scripts)
 npx claude-slim clean --lookback-days N  # Tune the unused-skill detection window
 npx claude-slim scan                     # Report only
+npx claude-slim scan --no-codex          # Skip the ~/.codex scan
 npx claude-slim doctor                   # Diagnose Node/Claude/session-log readiness
 npx claude-slim doctor --offline         # Same, without the version check (no network)
 npx claude-slim check-update             # Report-only version check
@@ -201,6 +202,7 @@ claude-slim never updates itself — that's your package manager's job, and writ
 - **`~/.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.
+- **`~/.codex/`** — scanned and reported when Codex is installed, never modified. Unused-skill detection is not offered there: Codex session logs record the skill catalog, not invocations, so there is no honest usage signal to act on.
 - **Anything outside `~/.claude/`** — a path-containment guard refuses destructive ops anywhere else, even if a tampered manifest asked it to.
 
 Only touched: entries under `~/.claude/skills/`, `~/.claude/plugins/cache/temp_local_*`, and `~/.claude/projects/*/memory/`. Skill and memory entries are moved to `skills.disabled/`; broken symlink files are unlinked and `temp_local_*` failed-install caches are removed outright.
@@ -245,17 +247,18 @@ Token counts come from [js-tiktoken](https://github.com/nicolo-ribaudo/js-tiktok
 
 ---
 
-## v2.8.0 — What's new
+## v2.10.0 — 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.**
+Codex support, scoped to what Codex can actually be asked.
 
-- **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.
+- **`~/.codex/` is scanned when present.** `scan` auto-detects a Codex install and reports its startup cost — local skills, plugin skills, agents, and `AGENTS.md`. `scan --json` gains a `codex` key; `--no-codex` skips it. On the dev machine this surfaced **10,926 tokens** nothing was measuring, including a `.bak` copy of a skill still costing 285 tokens every session.
+- Codex `SKILL.md` frontmatter matches Claude Code's exactly, so the existing listing parser is reused unchanged. Agents differ (`<name>.toml` with `description = "…"`) and get a small parser, verified against all 18 installed agents.
+- **Unused-skill detection is not offered for Codex, and `scan` says so.** Codex session logs record the skill *catalog* injected into each prompt, not invocations — every skill shows up in nearly every session, so using them as a usage signal would mark everything "used". Checked against 408 session files, a 56,724-row log database, and the tool-registry table before concluding.
+- **`~/.codex/` is read-only.** Nothing is moved or deleted there, same as `~/.claude/agents/`.
 
-Tests: 206 → 241 (+35).
+- **Backup-artifact detection, on both agents.** `foo.bak.20260711`, `foo (1)`, `foo~` and similar are flagged — Tier 2 on Claude Code (movable, restorable), report-only on Codex. Matching is limited to artifact *shapes*, so `backup-manager` and `test-engineer` are never touched.
+
+Tests: 279 → 347 (+68).
 
 For older release notes, see [CHANGELOG.md](CHANGELOG.md).
 

package/dist/cleaner.js

@@ -77,7 +77,8 @@ export async function cleanIssues(issues) {
                 issue.type === 'duplicate' ||
                 issue.type === 'skill_dup' ||
                 issue.type === 'oversized_skill' ||
-                issue.type === 'unused_skill') {
+                issue.type === 'unused_skill' ||
+                issue.type === 'backup_artifact') {
                 // Move skill directory to disabled — use name (not basename) to avoid namespace collisions
                 const safeName = issue.name.replace(/\//g, '--');
                 const dest = join(disabledDir, safeName);

package/dist/cli.js

@@ -11,6 +11,8 @@ import { readManifest } from './manifest.js';
 import { formatScanSummary, formatReportBox, calculateReport, } from './report.js';
 import { collectDoctorReport, formatDoctorReport } from './doctor.js';
 import { checkForUpdate, formatUpdateNotice } from './update-check.js';
+import { scanCodex } from './codex/index.js';
+import { formatCodexSummary } from './codex/report.js';
 import { resolveSelection, resolveRestoreSelection } from './selection.js';
 const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
 const { version: PKG_VERSION } = JSON.parse(readFileSync(pkgPath, 'utf-8'));
@@ -36,15 +38,22 @@ program
     .description('Scan environment and report issues')
     .option('--json', 'Output raw JSON')
     .option('--lookback-days <n>', 'Days of session history for skill-usage analysis', '60')
+    .option('--no-codex', 'Skip the ~/.codex scan even if Codex is installed')
     .action(async (opts) => {
     await initTokenizer();
     const result = await scan({ lookbackDays: parseNonNegativeInt(opts.lookbackDays, 60) });
+    // Codex is scanned when present. Reported only — it is never modified, and
+    // unused-skill detection is suppressed there for lack of a usage signal.
+    // commander maps `--no-codex` to `opts.codex === false`, not `opts.noCodex`.
+    const codex = opts.codex === false ? null : await scanCodex();
     await flushCache();
     if (opts.json) {
-        console.log(JSON.stringify(result, null, 2));
+        console.log(JSON.stringify({ ...result, codex }, null, 2));
     }
     else {
         console.log(formatScanSummary(result));
+        if (codex)
+            console.log(formatCodexSummary(codex));
     }
 });
 // --- doctor ---
@@ -211,6 +220,7 @@ program
     // temp_cache never counted toward totalTokensBefore).
     const SKILL_TYPES = new Set([
         'template', 'duplicate', 'skill_dup', 'oversized_skill', 'unused_skill',
+        'backup_artifact',
     ]);
     const removedSkillEntries = movedEntries.filter((e) => SKILL_TYPES.has(e.type));
     const removedMemoryTokens = movedEntries
@@ -244,7 +254,21 @@ program
     await flushCache();
 });
 // --- default (no subcommand) → run clean ---
+// Because the program itself carries an action, commander routes a mistyped
+// subcommand here and reports its own "too many arguments. Expected 0 arguments
+// but got 1" — which says nothing about what the user actually got wrong.
+// Accept the excess argument so we can name it instead.
+program.allowExcessArguments(true);
 program.action(async () => {
+    const stray = program.args;
+    if (stray.length > 0) {
+        const names = program.commands.map((c) => c.name()).join(', ');
+        console.error(`error: unknown command '${stray[0]}'`);
+        console.error(`available commands: ${names}`);
+        console.error(`run 'claude-slim --help' for usage`);
+        process.exitCode = 1;
+        return;
+    }
     await runCleanPipeline({ dryRun: false, auto: false, sessionsPerDay: 2, lookbackDays: 60 });
 });
 // --- shared clean pipeline ---

package/dist/codex/index.d.ts

@@ -0,0 +1,46 @@
+import { parseFrontmatterDescription } from '../scanner/skill-listing.js';
+export declare const UNUSED_DETECTION_REASON = "Codex session logs record the skill catalog, not invocations \u2014 there is no reliable usage signal to detect unused skills from.";
+export interface CodexSkill {
+    name: string;
+    path: string;
+    sizeBytes: number;
+    /** Full SKILL.md body — what the skill costs once invoked. */
+    tokens: number;
+    /** The `- name: description` line it adds to the system prompt. */
+    listingTokens: number;
+    source: 'local' | 'plugin';
+    pluginName?: string;
+    /** Set when the name looks like a leftover copy; reported, never acted on. */
+    backupArtifact?: string;
+}
+export interface CodexAgent {
+    name: string;
+    path: string;
+    sizeBytes: number;
+    tokens: number;
+    listingTokens: number;
+}
+export interface CodexScanResult {
+    root: string;
+    skills: CodexSkill[];
+    agents: CodexAgent[];
+    instructionsBytes: number;
+    instructionsTokens: number;
+    /** Skill + agent listing lines + AGENTS.md — the fixed startup cost. */
+    totalTokens: number;
+    unusedDetectionAvailable: false;
+    unusedDetectionReason: string;
+}
+export declare function getCodexDir(): string;
+export declare function isCodexInstalled(): Promise<boolean>;
+/**
+ * Pull `description` out of a Codex agent TOML.
+ *
+ * All 18 agents observed use a single-line `description = "…"`; the multi-line
+ * `"""` form is handled too so a future agent using it does not silently fall
+ * back to the flat estimate.
+ */
+export declare function parseTomlDescription(content: string): string | null;
+export declare function scanCodex(): Promise<CodexScanResult | null>;
+/** Re-exported so callers can reuse the frontmatter parser without a deep import. */
+export { parseFrontmatterDescription };

package/dist/codex/index.js

@@ -0,0 +1,192 @@
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { countTokensCached } from '../tokenizer.js';
+import { listingTokens, listingTokensFromContent, parseFrontmatterDescription } from '../scanner/skill-listing.js';
+import { safeReadFile, safeReaddir, isDirectory, isBrokenSymlink } from '../scanner/fs-walk.js';
+import { detectBackupArtifact } from '../scanner/backup-artifacts.js';
+// Codex support.
+//
+// The Claude Code scanner is deliberately left untouched: it is the
+// battle-tested path, and a shared abstraction would have meant refactoring
+// every scanner to prove a point. This module reuses the primitives that
+// genuinely transfer — the tokenizer and the frontmatter parser — and adds only
+// what differs.
+//
+// What transfers unchanged:
+//   ~/.codex/skills/<name>/SKILL.md   identical YAML frontmatter to Claude Code
+//   ~/.codex/plugins/cache/…/skills/  same nested layout
+//   ~/.codex/AGENTS.md                the CLAUDE.md equivalent
+//
+// What differs:
+//   agents are `<name>.toml` with `description = "…"`, not `<name>.md`
+//   there is no user-level commands/ directory
+//
+// What is NOT available: unused-skill detection. Codex session logs
+// (~/.codex/sessions/**.jsonl) record the skill *catalog* injected into each
+// system prompt, not invocations — every skill appears in nearly every session,
+// so using them as a usage signal would mark everything "used". Verified across
+// 408 session files, a 56,724-row log database, and the thread_dynamic_tools
+// table (a tool registry, not a history). See UNUSED_DETECTION_REASON.
+export const UNUSED_DETECTION_REASON = 'Codex session logs record the skill catalog, not invocations — there is no reliable usage signal to detect unused skills from.';
+export function getCodexDir() {
+    return join(homedir(), '.codex');
+}
+export async function isCodexInstalled() {
+    return isDirectory(getCodexDir());
+}
+/**
+ * Pull `description` out of a Codex agent TOML.
+ *
+ * All 18 agents observed use a single-line `description = "…"`; the multi-line
+ * `"""` form is handled too so a future agent using it does not silently fall
+ * back to the flat estimate.
+ */
+export function parseTomlDescription(content) {
+    const multi = /^description\s*=\s*"""\r?\n?([\s\S]*?)"""/m.exec(content);
+    if (multi) {
+        const joined = multi[1].split(/\r?\n/).map((l) => l.trim()).join(' ').trim();
+        return joined || null;
+    }
+    // These files carry the agent's whole prompt inside `developer_instructions =
+    // """…"""`, and that prose can contain a line that itself starts with
+    // `description = "…"`. Matching line-anchored across the raw text picks up the
+    // wrong one, so drop every triple-quoted block before looking for the
+    // single-line form. (The multi-line `description` case is handled above, i.e.
+    // before anything is stripped.)
+    const withoutBlocks = content.replace(/"""[\s\S]*?"""/g, '');
+    const single = /^description\s*=\s*"((?:[^"\\]|\\.)*)"/m.exec(withoutBlocks);
+    if (!single)
+        return null;
+    const unescaped = single[1].replace(/\\"/g, '"').replace(/\\\\/g, '\\').trim();
+    return unescaped || null;
+}
+async function scanLocalSkills() {
+    const dir = join(getCodexDir(), 'skills');
+    const entries = await safeReaddir(dir);
+    const results = [];
+    for (const entry of entries) {
+        // `.system` and other dot-directories are Codex internals, not user skills.
+        if (entry.startsWith('.'))
+            continue;
+        const skillDir = join(dir, entry);
+        if (!(await isDirectory(skillDir)))
+            continue;
+        const md = join(skillDir, 'SKILL.md');
+        if (await isBrokenSymlink(md))
+            continue;
+        const content = await safeReadFile(md);
+        if (content === null)
+            continue;
+        results.push({
+            name: entry,
+            path: skillDir,
+            sizeBytes: Buffer.byteLength(content),
+            tokens: countTokensCached(content, md),
+            listingTokens: listingTokensFromContent(entry, content),
+            source: 'local',
+            backupArtifact: detectBackupArtifact(entry)?.label,
+        });
+    }
+    return results;
+}
+/**
+ * Walk `plugins/cache/<marketplace>/<plugin>/<version>/skills/<skill>/SKILL.md`.
+ * Bounded rather than fully recursive so a deep or looping tree cannot wedge the
+ * scan — the layout is fixed and known.
+ */
+async function scanPluginSkills() {
+    const cache = join(getCodexDir(), 'plugins', 'cache');
+    const results = [];
+    for (const marketplace of await safeReaddir(cache)) {
+        if (marketplace.startsWith('.'))
+            continue;
+        const mDir = join(cache, marketplace);
+        if (!(await isDirectory(mDir)))
+            continue;
+        for (const plugin of await safeReaddir(mDir)) {
+            if (plugin.startsWith('.'))
+                continue;
+            const pDir = join(mDir, plugin);
+            if (!(await isDirectory(pDir)))
+                continue;
+            for (const version of await safeReaddir(pDir)) {
+                const skillsDir = join(pDir, version, 'skills');
+                if (!(await isDirectory(skillsDir)))
+                    continue;
+                for (const skill of await safeReaddir(skillsDir)) {
+                    const sDir = join(skillsDir, skill);
+                    if (!(await isDirectory(sDir)))
+                        continue;
+                    const md = join(sDir, 'SKILL.md');
+                    if (await isBrokenSymlink(md))
+                        continue;
+                    const content = await safeReadFile(md);
+                    if (content === null)
+                        continue;
+                    results.push({
+                        name: skill,
+                        path: sDir,
+                        sizeBytes: Buffer.byteLength(content),
+                        tokens: countTokensCached(content, md),
+                        listingTokens: listingTokensFromContent(skill, content),
+                        source: 'plugin',
+                        pluginName: plugin,
+                    });
+                }
+            }
+        }
+    }
+    return results;
+}
+async function scanAgents() {
+    const dir = join(getCodexDir(), 'agents');
+    const results = [];
+    for (const entry of await safeReaddir(dir)) {
+        if (!entry.endsWith('.toml'))
+            continue;
+        const path = join(dir, entry);
+        if (await isBrokenSymlink(path))
+            continue;
+        const content = await safeReadFile(path);
+        if (content === null)
+            continue;
+        const name = entry.slice(0, -'.toml'.length);
+        results.push({
+            name,
+            path,
+            sizeBytes: Buffer.byteLength(content),
+            tokens: countTokensCached(content, path),
+            listingTokens: listingTokens(name, parseTomlDescription(content)),
+        });
+    }
+    return results;
+}
+export async function scanCodex() {
+    if (!(await isCodexInstalled()))
+        return null;
+    const [local, plugin, agents] = await Promise.all([
+        scanLocalSkills(),
+        scanPluginSkills(),
+        scanAgents(),
+    ]);
+    const instructionsPath = join(getCodexDir(), 'AGENTS.md');
+    const instructions = await safeReadFile(instructionsPath);
+    const instructionsBytes = instructions ? Buffer.byteLength(instructions) : 0;
+    const instructionsTokens = instructions
+        ? countTokensCached(instructions, instructionsPath)
+        : 0;
+    const skills = [...local, ...plugin];
+    const listing = (xs) => xs.reduce((sum, x) => sum + x.listingTokens, 0);
+    return {
+        root: getCodexDir(),
+        skills,
+        agents,
+        instructionsBytes,
+        instructionsTokens,
+        totalTokens: listing(skills) + listing(agents) + instructionsTokens,
+        unusedDetectionAvailable: false,
+        unusedDetectionReason: UNUSED_DETECTION_REASON,
+    };
+}
+/** Re-exported so callers can reuse the frontmatter parser without a deep import. */
+export { parseFrontmatterDescription };

package/dist/codex/report.d.ts

@@ -0,0 +1,9 @@
+import type { CodexScanResult } from './index.js';
+/**
+ * Render the Codex section appended to `scan` output.
+ *
+ * Deliberately reports only what Codex can actually tell us. The "not
+ * available" line for unused-skill detection is not an apology — stating the
+ * limit is what keeps the tool from inventing a signal it does not have.
+ */
+export declare function formatCodexSummary(result: CodexScanResult): string;

package/dist/codex/report.js

@@ -0,0 +1,56 @@
+const TOP_N = 5;
+/**
+ * Render the Codex section appended to `scan` output.
+ *
+ * Deliberately reports only what Codex can actually tell us. The "not
+ * available" line for unused-skill detection is not an apology — stating the
+ * limit is what keeps the tool from inventing a signal it does not have.
+ */
+export function formatCodexSummary(result) {
+    const lines = [];
+    const local = result.skills.filter((s) => s.source === 'local');
+    const plugin = result.skills.filter((s) => s.source === 'plugin');
+    const sum = (xs) => xs.reduce((acc, x) => acc + x.listingTokens, 0);
+    lines.push('');
+    lines.push('\x1b[1m=== codex ===\x1b[0m');
+    lines.push('');
+    lines.push(`  \x1b[90m${result.root}\x1b[0m`);
+    lines.push('');
+    const row = (label, count, tokens) => `    ${label.padEnd(24)} ${count.padStart(8)}  ${tokens.toLocaleString().padStart(8)} tok`;
+    lines.push('\x1b[1m  STARTUP COST\x1b[0m');
+    lines.push(row('Local skills', `${local.length}`, sum(local)));
+    lines.push(row('Plugin skills', `${plugin.length}`, sum(plugin)));
+    lines.push(row('Agents', `${result.agents.length}`, sum(result.agents)));
+    lines.push(row('AGENTS.md', `${(result.instructionsBytes / 1024).toFixed(1)}KB`, result.instructionsTokens));
+    lines.push(`    ${'─'.repeat(46)}`);
+    lines.push(row('Total', '', result.totalTokens));
+    const heaviest = [...result.skills].sort((a, b) => b.listingTokens - a.listingTokens).slice(0, TOP_N);
+    if (heaviest.length > 0) {
+        lines.push('');
+        lines.push(`\x1b[1m  HEAVIEST LISTINGS\x1b[0m (top ${heaviest.length})`);
+        for (const s of heaviest) {
+            const origin = s.pluginName ? `plugin:${s.pluginName}` : 'local';
+            // Names can exceed the column (backup copies like `foo.bak.20260711`);
+            // truncate so the token column stays aligned.
+            const name = s.name.length > 30 ? `${s.name.slice(0, 29)}…` : s.name;
+            lines.push(`    ${name.padEnd(30)} ${String(s.listingTokens).padStart(5)} tok  \x1b[90m${origin}\x1b[0m`);
+        }
+    }
+    const backups = result.skills.filter((s) => s.backupArtifact);
+    if (backups.length > 0) {
+        lines.push('');
+        lines.push(`\x1b[1m  LIKELY BACKUP COPIES\x1b[0m (${backups.length})`);
+        for (const b of backups) {
+            lines.push(`    ${b.name.length > 30 ? `${b.name.slice(0, 29)}…` : b.name.padEnd(30)} ` +
+                `${String(b.listingTokens).padStart(5)} tok  \x1b[90m${b.backupArtifact}\x1b[0m`);
+        }
+        lines.push(`    \x1b[90mNot removed — ~/.codex/ is read-only here. Delete manually if stale.\x1b[0m`);
+    }
+    lines.push('');
+    lines.push(`  \x1b[33m!\x1b[0m Unused-skill detection unavailable for Codex.`);
+    lines.push(`    \x1b[90m${result.unusedDetectionReason}\x1b[0m`);
+    lines.push('');
+    lines.push(`  \x1b[90mReported only — claude-slim never modifies ~/.codex/.\x1b[0m`);
+    lines.push('');
+    return lines.join('\n');
+}

package/dist/scanner/backup-artifacts.d.ts

@@ -0,0 +1,11 @@
+export interface BackupMatch {
+    /** Which convention matched, for showing the user why. */
+    label: string;
+}
+/**
+ * Return why `name` looks like a backup artifact, or null if it does not.
+ *
+ * Matches on the entry name only. Callers decide what to do with it — the
+ * Claude path raises a cleanup issue, the Codex path only reports.
+ */
+export declare function detectBackupArtifact(name: string): BackupMatch | null;

package/dist/scanner/backup-artifacts.js

@@ -0,0 +1,46 @@
+// Backup-artifact detection.
+//
+// Unused-skill detection needs a usage signal. This does not: a name like
+// `humanize-korean.bak.20260711-100101` is self-evidently a leftover copy
+// regardless of whether anything ever invoked it. That makes it the one useful
+// cleanup hint that works even on Codex, where session logs carry no
+// invocation history.
+//
+// The whole risk here is false positives. `backup-manager`, `test-engineer`,
+// and `old-school-linter` are real skills whose names merely contain the words
+// "backup", "test", and "old". So these patterns match only *artifact shapes* —
+// dotted segments, trailing markers, timestamp suffixes — never a bare
+// substring anywhere in the name.
+const PATTERNS = [
+    // `foo.bak`, `foo.bak.20260711` — dotted segment, not the word "bak" inside a name.
+    { re: /\.bak(\.|$)/i, label: '.bak' },
+    { re: /\.backup(\.|$)/i, label: '.backup' },
+    { re: /\.orig(\.|$)/i, label: '.orig' },
+    { re: /\.old(\.|$)/i, label: '.old' },
+    { re: /\.save(\.|$)/i, label: '.save' },
+    { re: /\.disabled(\.|$)/i, label: '.disabled' },
+    // `foo.20260711` / `foo.20260711-100101` — a dated snapshot.
+    { re: /\.\d{8}(-\d{6})?(\.|$)/, label: 'timestamp suffix' },
+    // `foo-2026-07-11`
+    { re: /[-_]\d{4}-\d{2}-\d{2}(\.|$)/, label: 'dated suffix' },
+    // Editor/rsync leftovers.
+    { re: /~$/, label: 'editor backup' },
+    // `foo copy`, `foo-copy`, `foo (copy)` — trailing only.
+    { re: /[ _-]\(?copy\)?$/i, label: 'copy suffix' },
+    { re: /^copy[ _-]of[ _-]/i, label: 'copy-of prefix' },
+    // `foo (1)` — duplicate-download naming.
+    { re: / \(\d+\)$/, label: 'numbered duplicate' },
+];
+/**
+ * Return why `name` looks like a backup artifact, or null if it does not.
+ *
+ * Matches on the entry name only. Callers decide what to do with it — the
+ * Claude path raises a cleanup issue, the Codex path only reports.
+ */
+export function detectBackupArtifact(name) {
+    for (const { re, label } of PATTERNS) {
+        if (re.test(name))
+            return { label };
+    }
+    return null;
+}

package/dist/scanner/detectors.js

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
 import { getPluginsDir } from '../paths.js';
 import { OVERSIZED_SKILL_BYTES, OVERSIZED_MEMORY_BYTES, SKILL_PROMPT_OVERHEAD_TOKENS, } from './constants.js';
+import { detectBackupArtifact } from './backup-artifacts.js';
 const brokenSymlinkDetector = {
     name: 'broken_symlink',
     detect({ brokenSymlinks }) {
@@ -241,6 +242,30 @@ const disabledPluginDetector = {
 };
 // The full registry. Order only matters for ties in the tier sort.
 // New detectors: define above, add here, update CONTRIBUTING.md's issue-type table.
+// Backup leftovers are the one cleanup hint that needs no usage signal: a name
+// like `foo.bak.20260711` announces itself. Tier 2 rather than Tier 1 — a
+// backup still has some value, so the user confirms rather than it being
+// pre-selected. The move is reversible via `restore` like any other skill.
+const backupArtifactDetector = {
+    name: 'backup_artifact',
+    detect({ localSkills }) {
+        const issues = [];
+        for (const skill of localSkills) {
+            const match = detectBackupArtifact(skill.name);
+            if (!match)
+                continue;
+            issues.push({
+                type: 'backup_artifact',
+                tier: 2,
+                name: skill.name,
+                detail: `looks like a backup copy (${match.label})`,
+                tokens: skill.tokens,
+                path: skill.path,
+            });
+        }
+        return issues;
+    },
+};
 export const detectors = [
     brokenSymlinkDetector,
     templateDetector,
@@ -253,6 +278,7 @@ export const detectors = [
     unusedSkillDetector,
     unusedPluginDetector,
     disabledPluginDetector,
+    backupArtifactDetector,
 ];
 export function classifyIssues(ctx, registry = detectors) {
     const issues = registry.flatMap((d) => d.detect(ctx));

package/dist/tokenizer.js

@@ -39,11 +39,72 @@ export async function initTokenizer() {
 function hashContent(content) {
     return createHash('md5').update(content).digest('hex');
 }
+// js-tiktoken's BPE is quadratic in the length of a single whitespace-free run.
+// Ordinary prose of any length is fine — the pre-tokenizer splits on whitespace,
+// so 8,000 characters of normal text encodes in ~1ms. One long unbroken run does
+// not: measured on cl100k_base, 800 characters of Hangul costs ~450ms, 3,200
+// costs ~6.8s, and a 60,000-character run wedges the scan for minutes with no
+// output at all. Real SKILL.md files reach this with base64 blobs, minified
+// snippets, rule separators, and CJK text.
+//
+// 512 sits above anything a normal word, path, or URL produces and well below
+// where the curve turns painful.
+const MAX_ENCODE_RUN = 512;
+const LONG_RUN_PATTERN = /\S{513,}/;
+const FALLBACK_CHARS_PER_TOKEN = 4;
+/**
+ * Estimate an over-long run by encoding a bounded prefix and scaling.
+ *
+ * A fixed characters-per-token divisor cannot work here: measured over 1,000-char
+ * runs, cl100k_base yields 0.8 chars/token for Hangul but 8.0 for a repeated
+ * ASCII character — a 10× spread. Sampling the run's own prefix adapts to
+ * whatever it actually contains (base64, hex, minified JSON, CJK) at the cost of
+ * exactly one bounded encode.
+ */
+function estimateRun(segment, encode) {
+    const sample = segment.slice(0, MAX_ENCODE_RUN);
+    const sampleTokens = encode(sample).length;
+    if (sampleTokens === 0)
+        return 0;
+    return Math.ceil((sampleTokens * segment.length) / sample.length);
+}
+/**
+ * Encode `text`, estimating any whitespace-free run longer than
+ * {@link MAX_ENCODE_RUN} instead of feeding the whole run to the BPE.
+ *
+ * Text without such a run takes the fast path and is encoded whole, so counts
+ * for well-formed files are identical to encoding directly.
+ */
+function encodeBounded(text, encode) {
+    if (!LONG_RUN_PATTERN.test(text)) {
+        return encode(text).length;
+    }
+    let total = 0;
+    let buffered = '';
+    // Splitting on a captured group keeps the whitespace in the stream, so the
+    // buffered pieces still look to the encoder like the original text.
+    for (const segment of text.split(/(\s+)/)) {
+        if (segment.length > MAX_ENCODE_RUN) {
+            if (buffered) {
+                total += encode(buffered).length;
+                buffered = '';
+            }
+            total += estimateRun(segment, encode);
+            continue;
+        }
+        buffered += segment;
+    }
+    if (buffered) {
+        total += encode(buffered).length;
+    }
+    return total;
+}
 export function countTokens(text) {
     if (useFallback || !encoder) {
-        return Math.ceil(text.length / 4);
+        return Math.ceil(text.length / FALLBACK_CHARS_PER_TOKEN);
     }
-    return encoder.encode(text).length;
+    const enc = encoder;
+    return encodeBounded(text, (s) => enc.encode(s));
 }
 export function countTokensCached(text, filePath) {
     const hash = hashContent(text);

package/dist/types.d.ts

@@ -34,7 +34,7 @@ export interface PluginInfo {
     status?: 'enabled' | 'disabled';
 }
 export type IssueTier = 1 | 2 | 3;
-export type IssueType = 'broken_symlink' | 'template' | 'skill_dup' | 'duplicate' | 'oversized_memory' | 'oversized_skill' | 'unused_skill' | 'unused_plugin' | 'disabled_plugin' | 'stale_project' | 'temp_cache';
+export type IssueType = 'broken_symlink' | 'template' | 'skill_dup' | 'duplicate' | 'oversized_memory' | 'oversized_skill' | 'unused_skill' | 'unused_plugin' | 'disabled_plugin' | 'stale_project' | 'temp_cache' | 'backup_artifact';
 export interface Issue {
     type: IssueType;
     tier: IssueTier;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-slim",
-  "version": "2.9.0",
+  "version": "2.10.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": {