claude-slim 2.9.1 → 2.11.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, since v2.11, cleanable under the same tiers. Moves go to `~/.codex/skills.disabled/` and reverse with `restore`. The path guard is per-agent, so a Codex item can never resolve into `~/.claude/`. Unused-skill detection is still 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,14 +247,16 @@ Token counts come from [js-tiktoken](https://github.com/nicolo-ribaudo/js-tiktok
 
 ---
 
-## v2.9.1 — What's new
+## v2.11.0 — What's new
 
-Found while stress-testing the scanner against deliberately hostile `~/.claude` fixtures.
+Codex gets the same tiered propose-and-choose cleanup Claude Code has, minus the two categories Codex cannot honestly support.
 
-- **Fixed: `scan` could hang forever on a single long line.** js-tiktoken's BPE is quadratic in the length of one whitespace-free run. Normal prose is fine (8,000 characters encodes in ~1ms), but 800 characters of Hangul cost ~450ms, 3,200 cost ~6.8s, and a 60,000-character run wedged `scan` past 20 seconds with **no output at all** — indistinguishable from a freeze. `SKILL.md` files hit this via base64 blobs, minified snippets, embedded JSON schemas, and CJK text. Long runs are now estimated by encoding a bounded prefix and scaling; **files without one produce byte-identical counts** (verified across 71 installed skills: 70 exact, one moved 0.01%). Hostile fixture: 20s+ → 1.78s, with no measurable cost on ordinary input.
-- **Fixed: a mistyped subcommand blamed the wrong thing.** `claude-slim scam` printed `error: too many arguments. Expected 0 arguments but got 1`. It now names the unknown command and lists the real ones.
+- **Codex cleanup, tiered.** Five of seven categories carry over because they are filesystem facts, not usage inferences: broken symlinks and unfilled templates (Tier 1), install leftovers in `~/.codex/.tmp` (Tier 1 — 146MB on the dev machine), backup copies and plugin-shadowed duplicates (Tier 2), oversized skills (Tier 3). Codex items join the same numbered list tagged `[codex]`. `--no-codex` opts out.
+- **`~/.codex/skills.disabled/`** — moves are reversible through the same `restore`, and manifest entries record which agent they came from.
+- **The path guard is now per-agent.** Not "inside any known root" — a Codex issue must not resolve into `~/.claude/` and vice versa, so a tampered manifest cannot cross between agents.
+- `unused_skill` and `oversized_memory` remain unavailable for Codex: no invocation record, and no `~/.codex/projects/*/memory/`.
 
-Tests: 266 → 279 (+13).
+Tests: 347 → 374 (+27), the guard suite being the point — cross-agent isolation both directions, traversal escapes, and a `~/.claude-backup` sibling a naive `startsWith` would have allowed.
 
 For older release notes, see [CHANGELOG.md](CHANGELOG.md).
 

package/dist/cleaner.js

@@ -1,7 +1,7 @@
 import { rename, readdir, rmdir, rm, unlink, lstat, mkdir } from 'node:fs/promises';
 import { join, dirname, resolve, sep } from 'node:path';
-import { appendManifest, ensureDisabledDir, getDisabledDir, removeEntry, recordDisabledPlugin, removeDisabledPlugin } from './manifest.js';
-import { assertInsideClaudeDir, getSkillsDir, getProjectsDir } from './paths.js';
+import { appendManifest, ensureDisabledDir, removeEntry, recordDisabledPlugin, removeDisabledPlugin } from './manifest.js';
+import { assertInsideAgentRoot, getAgentRoot, getAgentDisabledDir, getSkillsDir, getProjectsDir } from './paths.js';
 import { disablePlugin, enablePlugin, isClaudeCliAvailable, ClaudeCliMissingError } from './plugin-runtime.js';
 // Restrict a restore target to a specific subtree of ~/.claude/. Complements
 // assertInsideClaudeDir: a tampered manifest could still name a legal
@@ -40,8 +40,6 @@ async function recordOrRollback(entry, rollback) {
     }
 }
 export async function cleanIssues(issues) {
-    await ensureDisabledDir();
-    const disabledDir = getDisabledDir();
     const moved = [];
     const skipped = [];
     const errors = [];
@@ -54,15 +52,20 @@ export async function cleanIssues(issues) {
         claudeCliMissing = true;
     }
     for (const issue of issues) {
+        // Scope every path decision to the issue's own agent, so a Codex issue can
+        // never resolve into ~/.claude/ (or the reverse).
+        const agent = issue.agent ?? 'claude';
+        const disabledDir = await ensureDisabledDir(agent);
         try {
             // unused_plugin and report-only types don't touch filesystem paths directly
             if (issue.type !== 'unused_plugin' && issue.type !== 'oversized_memory' && issue.type !== 'disabled_plugin') {
-                assertInsideClaudeDir(issue.path);
+                assertInsideAgentRoot(issue.path, agent);
             }
             if (issue.type === 'broken_symlink') {
                 await unlink(issue.path);
                 const entry = {
                     date: new Date().toISOString(),
+                    agent,
                     name: issue.name,
                     from: issue.path,
                     type: issue.type,
@@ -77,13 +80,15 @@ 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);
                 await rename(issue.path, dest);
                 const entry = {
                     date: new Date().toISOString(),
+                    agent,
                     name: issue.name,
                     from: issue.path,
                     type: issue.type,
@@ -107,6 +112,7 @@ export async function cleanIssues(issues) {
                 }
                 const entry = {
                     date: new Date().toISOString(),
+                    agent,
                     name: issue.name,
                     from: issue.path,
                     type: issue.type,
@@ -130,6 +136,7 @@ export async function cleanIssues(issues) {
                 await rename(issue.path, backupDir);
                 const entry = {
                     date: new Date().toISOString(),
+                    agent,
                     name: issue.name,
                     from: issue.path,
                     type: issue.type,
@@ -209,7 +216,7 @@ export async function restoreItem(entry) {
         return;
     }
     const legacyEntry = entry;
-    assertInsideClaudeDir(legacyEntry.from);
+    assertInsideAgentRoot(legacyEntry.from, legacyEntry.agent ?? 'claude');
     if (legacyEntry.type === 'broken_symlink') {
         throw new Error(`Broken symlinks cannot be restored (${legacyEntry.name})`);
     }
@@ -219,7 +226,9 @@ export async function restoreItem(entry) {
     if (legacyEntry.type === 'temp_cache') {
         throw new Error(`Temp caches were deleted and cannot be restored (${legacyEntry.name})`);
     }
-    const disabledDir = getDisabledDir();
+    // Resolve the store from the entry's own agent — a Codex skill was parked
+    // under ~/.codex/skills.disabled and must be looked for there.
+    const disabledDir = getAgentDisabledDir(('agent' in entry ? entry.agent : undefined) ?? 'claude');
     if (legacyEntry.type === 'stale_project') {
         // Type-scoped path guard: stale-project backups must restore under
         // ~/.claude/projects/. Prevents a tampered manifest from redirecting a
@@ -238,7 +247,9 @@ export async function restoreItem(entry) {
     }
     else {
         // Type-scoped path guard: skill restores must land under ~/.claude/skills/.
-        assertInsideSubtree(legacyEntry.from, getSkillsDir(), 'skill');
+        // Per-agent skills/ subtree: a Codex entry restores under ~/.codex/skills,
+        // never ~/.claude/skills.
+        assertInsideSubtree(legacyEntry.from, join(getAgentRoot(legacyEntry.agent ?? 'claude'), 'skills'), 'skill');
         // Restore skill directory using the same naming as cleanIssues
         const safeName = legacyEntry.name.replace(/\//g, '--');
         const src = join(disabledDir, safeName);

package/dist/cli.js

@@ -11,6 +11,9 @@ 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 { classifyCodexIssues } from './codex/detectors.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 +39,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 ---
@@ -99,12 +109,14 @@ program
     .option('--auto', 'Non-interactive: auto-select Tier 1 items only')
     .option('--sessions-per-day <n>', 'Sessions per day for savings estimate', '2')
     .option('--lookback-days <n>', 'Days of session history for skill-usage analysis', '60')
+    .option('--no-codex', 'Skip ~/.codex entirely')
     .action(async (opts) => {
     await runCleanPipeline({
         dryRun: !!opts.dryRun,
         auto: !!opts.auto,
         sessionsPerDay: parseNonNegativeInt(opts.sessionsPerDay, 2),
         lookbackDays: parseNonNegativeInt(opts.lookbackDays, 60),
+        codex: opts.codex !== false,
     });
 });
 // --- restore ---
@@ -211,6 +223,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
@@ -259,12 +272,20 @@ program.action(async () => {
         process.exitCode = 1;
         return;
     }
-    await runCleanPipeline({ dryRun: false, auto: false, sessionsPerDay: 2, lookbackDays: 60 });
+    await runCleanPipeline({ dryRun: false, auto: false, sessionsPerDay: 2, lookbackDays: 60, codex: true });
 });
 // --- shared clean pipeline ---
 async function runCleanPipeline(opts) {
     await initTokenizer();
     const result = await scan({ lookbackDays: opts.lookbackDays });
+    // Codex issues join the same tiered list. They carry `agent: 'codex'`, which
+    // is what keeps the cleaner's path guard pointed at ~/.codex/.
+    const codexContents = new Map();
+    const codexScan = opts.codex ? await scanCodex(codexContents) : null;
+    if (codexScan) {
+        result.issues.push(...(await classifyCodexIssues({ scan: codexScan, contents: codexContents })));
+        result.issues.sort((a, b) => a.tier - b.tier || b.tokens - a.tokens);
+    }
     if (result.issues.length === 0) {
         console.log('\n  \x1b[32mAlready slim!\x1b[0m No issues found.\n');
         await flushCache();

package/dist/codex/detectors.d.ts

@@ -0,0 +1,26 @@
+import type { Issue } from '../types.js';
+import type { CodexScanResult } from './index.js';
+export interface CodexDetectorContext {
+    scan: CodexScanResult;
+    /** SKILL.md contents keyed by absolute path, so detectors need not re-read. */
+    contents: Map<string, string>;
+}
+/** Tier 1 — a SKILL.md symlink whose target is gone. Contributes nothing. */
+export declare function detectBrokenSymlinks(ctx: CodexDetectorContext): Promise<Issue[]>;
+/** Tier 1 — a scaffold nobody filled in. */
+export declare function detectTemplates(ctx: CodexDetectorContext): Issue[];
+/**
+ * Tier 1 — `~/.codex/.tmp`, where interrupted plugin installs accumulate.
+ * Sized rather than token-counted: this is disk, not context.
+ */
+export declare function detectInstallLeftovers(): Promise<Issue[]>;
+/** Tier 2 — a leftover copy, recognised by name shape alone. */
+export declare function detectBackups(ctx: CodexDetectorContext): Issue[];
+/**
+ * Tier 2 — a local skill shadowed by a plugin-provided one of the same name.
+ * Removing the local copy leaves the plugin version in place.
+ */
+export declare function detectDuplicates(ctx: CodexDetectorContext): Issue[];
+/** Tier 3 — large enough to be worth a look, but possibly still in use. */
+export declare function detectOversized(ctx: CodexDetectorContext): Issue[];
+export declare function classifyCodexIssues(ctx: CodexDetectorContext): Promise<Issue[]>;

package/dist/codex/detectors.js

@@ -0,0 +1,110 @@
+import { join } from 'node:path';
+import { getCodexDir } from '../paths.js';
+import { OVERSIZED_SKILL_BYTES } from '../scanner/constants.js';
+import { isDirectory, safeReaddir, getDirSize, isBrokenSymlink } from '../scanner/fs-walk.js';
+// Codex cleanup candidates, in the same three tiers the Claude path uses.
+//
+// Five of Claude's seven categories carry over unchanged, because they are
+// filesystem facts rather than usage inferences:
+//
+//   broken symlinks · empty templates · duplicates · oversized · install leftovers
+//
+// The two that do not:
+//   unused_skill    — no invocation record exists in Codex session logs
+//   oversized_memory— Codex has no ~/.codex/projects/*/memory/ equivalent
+//
+// Every issue produced here carries `agent: 'codex'`, which is what keeps the
+// cleaner's path guard scoped to ~/.codex/ and unable to reach ~/.claude/.
+const TEMPLATE_MARKER = 'Replace with description';
+/** MB once it is worth calling MB; KB below that, so a 3KB leftover is not "0MB". */
+function formatBytes(bytes) {
+    const mb = bytes / 1024 / 1024;
+    return mb >= 1 ? `${mb.toFixed(0)}MB` : `${Math.max(1, Math.round(bytes / 1024))}KB`;
+}
+function issue(type, tier, skill, detail) {
+    return { type, tier, agent: 'codex', name: skill.name, path: skill.path, tokens: skill.tokens, detail };
+}
+/** Tier 1 — a SKILL.md symlink whose target is gone. Contributes nothing. */
+export async function detectBrokenSymlinks(ctx) {
+    const out = [];
+    const skillsDir = join(getCodexDir(), 'skills');
+    for (const entry of await safeReaddir(skillsDir)) {
+        if (entry.startsWith('.'))
+            continue;
+        const dir = join(skillsDir, entry);
+        if (!(await isDirectory(dir)))
+            continue;
+        const md = join(dir, 'SKILL.md');
+        if (await isBrokenSymlink(md)) {
+            out.push({
+                type: 'broken_symlink', tier: 1, agent: 'codex',
+                name: entry, path: md, tokens: 0, detail: 'dead symlink',
+            });
+        }
+    }
+    return out;
+}
+/** Tier 1 — a scaffold nobody filled in. */
+export function detectTemplates(ctx) {
+    return ctx.scan.skills
+        .filter((s) => s.source === 'local')
+        .filter((s) => ctx.contents.get(join(s.path, 'SKILL.md'))?.includes(TEMPLATE_MARKER))
+        .map((s) => issue('template', 1, s, 'unfilled template'));
+}
+/**
+ * Tier 1 — `~/.codex/.tmp`, where interrupted plugin installs accumulate.
+ * Sized rather than token-counted: this is disk, not context.
+ */
+export async function detectInstallLeftovers() {
+    const out = [];
+    for (const name of ['.tmp', '.remote-plugin-install-staging']) {
+        const path = join(getCodexDir(), name);
+        if (!(await isDirectory(path)))
+            continue;
+        const bytes = await getDirSize(path);
+        if (bytes === 0)
+            continue;
+        out.push({
+            type: 'temp_cache', tier: 1, agent: 'codex',
+            name, path, tokens: 0,
+            detail: `${formatBytes(bytes)} of install leftovers`,
+        });
+    }
+    return out;
+}
+/** Tier 2 — a leftover copy, recognised by name shape alone. */
+export function detectBackups(ctx) {
+    return ctx.scan.skills
+        .filter((s) => s.source === 'local' && s.backupArtifact)
+        .map((s) => issue('backup_artifact', 2, s, `looks like a backup copy (${s.backupArtifact})`));
+}
+/**
+ * Tier 2 — a local skill shadowed by a plugin-provided one of the same name.
+ * Removing the local copy leaves the plugin version in place.
+ */
+export function detectDuplicates(ctx) {
+    const fromPlugins = new Set(ctx.scan.skills.filter((s) => s.source === 'plugin').map((s) => s.name));
+    return ctx.scan.skills
+        .filter((s) => s.source === 'local' && fromPlugins.has(s.name))
+        .map((s) => issue('duplicate', 2, s, 'also provided by a plugin'));
+}
+/** Tier 3 — large enough to be worth a look, but possibly still in use. */
+export function detectOversized(ctx) {
+    return ctx.scan.skills
+        .filter((s) => s.source === 'local' && s.sizeBytes > OVERSIZED_SKILL_BYTES)
+        .map((s) => issue('oversized_skill', 3, s, `${Math.round(s.sizeBytes / 1024)}KB`));
+}
+export async function classifyCodexIssues(ctx) {
+    const [symlinks, leftovers] = await Promise.all([
+        detectBrokenSymlinks(ctx),
+        detectInstallLeftovers(),
+    ]);
+    return [
+        ...symlinks,
+        ...detectTemplates(ctx),
+        ...leftovers,
+        ...detectBackups(ctx),
+        ...detectDuplicates(ctx),
+        ...detectOversized(ctx),
+    ].sort((a, b) => a.tier - b.tier || b.tokens - a.tokens);
+}

package/dist/codex/index.d.ts

@@ -0,0 +1,51 @@
+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;
+/**
+ * @param contents optional sink for SKILL.md bodies, so detectors can inspect
+ *   them without a second pass over the filesystem. Deliberately an out-param
+ *   rather than part of the result: it must not land in `scan --json`.
+ */
+export declare function scanCodex(contents?: Map<string, string>): 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,198 @@
+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(contents) {
+    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;
+        contents?.set(md, content);
+        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;
+}
+/**
+ * @param contents optional sink for SKILL.md bodies, so detectors can inspect
+ *   them without a second pass over the filesystem. Deliberately an out-param
+ *   rather than part of the result: it must not land in `scan --json`.
+ */
+export async function scanCodex(contents) {
+    if (!(await isCodexInstalled()))
+        return null;
+    const [local, plugin, agents] = await Promise.all([
+        scanLocalSkills(contents),
+        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/manifest.d.ts

@@ -1,6 +1,8 @@
 import type { Manifest, ManifestEntry, AnyManifestEntry, DisabledPluginEntry } from './types.js';
+import type { AgentId } from './paths.js';
 export declare function getDisabledDir(): string;
-export declare function ensureDisabledDir(): Promise<void>;
+/** Create (if needed) and return the disabled-skill store for one agent. */
+export declare function ensureDisabledDir(agent?: AgentId): Promise<string>;
 export declare function migrateLegacyIfNeeded(): Promise<void>;
 export declare function readManifestV2(): Promise<Manifest>;
 export declare function writeManifestV2(manifest: Manifest): Promise<void>;

package/dist/manifest.js

@@ -1,10 +1,13 @@
 import { readFile, writeFile, mkdir, rename, access } from 'node:fs/promises';
-import { getDisabledDir as getDir, getManifestPath, getLegacyManifestPath, } from './paths.js';
+import { getDisabledDir as getDir, getAgentDisabledDir, getManifestPath, getLegacyManifestPath, } from './paths.js';
 export function getDisabledDir() {
     return getDir();
 }
-export async function ensureDisabledDir() {
-    await mkdir(getDisabledDir(), { recursive: true });
+/** Create (if needed) and return the disabled-skill store for one agent. */
+export async function ensureDisabledDir(agent = 'claude') {
+    const dir = getAgentDisabledDir(agent);
+    await mkdir(dir, { recursive: true });
+    return dir;
 }
 async function pathExists(p) {
     try {

package/dist/paths.d.ts

@@ -14,4 +14,23 @@ export declare function getDisabledDir(): string;
 export declare function getCurrentProjectSlug(cwd?: string): string;
 export declare function getManifestPath(): string;
 export declare function getLegacyManifestPath(): string;
+/** The agents claude-slim is allowed to touch. Adding one widens what every
+ *  destructive operation may reach, so this list is the security boundary. */
+export type AgentId = 'claude' | 'codex';
+export declare function getCodexDir(): string;
+export declare function getAgentRoot(agent: AgentId): string;
+export declare function getAgentDisabledDir(agent: AgentId): string;
+/**
+ * Refuse to operate on a path outside the given agent's root. Guards destructive
+ * operations (rename/rm/unlink) against tampered manifests and scanner bugs.
+ *
+ * Deliberately per-agent rather than "inside any known root": a Codex issue must
+ * not be able to reach into ~/.claude/ and vice versa. Widening this to a single
+ * combined check would let one bad manifest entry cross between agents, which is
+ * exactly the failure this exists to prevent.
+ */
+export declare function assertInsideAgentRoot(p: string, agent: AgentId): void;
+/** Back-compat wrapper — the Claude path is by far the most common caller. */
 export declare function assertInsideClaudeDir(p: string): void;
+/** Which agent owns this path, or null if it belongs to neither. */
+export declare function agentForPath(p: string): AgentId | null;

package/dist/paths.js

@@ -32,12 +32,44 @@ export function getManifestPath() {
 export function getLegacyManifestPath() {
     return join(getDisabledDir(), '.claude-slim-manifest.jsonl');
 }
-// Refuse to operate on a path outside ~/.claude/. Guards destructive operations
-// (rename/rm/unlink) from acting on attacker-tampered manifests or scanner bugs.
-export function assertInsideClaudeDir(p) {
-    const resolved = resolve(p);
-    const root = resolve(getClaudeDir());
-    if (resolved !== root && !resolved.startsWith(root + sep)) {
-        throw new Error(`Refusing to operate on path outside ~/.claude/: ${p}`);
+export function getCodexDir() {
+    return join(homedir(), '.codex');
+}
+export function getAgentRoot(agent) {
+    return agent === 'claude' ? getClaudeDir() : getCodexDir();
+}
+export function getAgentDisabledDir(agent) {
+    return join(getAgentRoot(agent), 'skills.disabled');
+}
+function isInside(child, root) {
+    const c = resolve(child);
+    const r = resolve(root);
+    return c === r || c.startsWith(r + sep);
+}
+/**
+ * Refuse to operate on a path outside the given agent's root. Guards destructive
+ * operations (rename/rm/unlink) against tampered manifests and scanner bugs.
+ *
+ * Deliberately per-agent rather than "inside any known root": a Codex issue must
+ * not be able to reach into ~/.claude/ and vice versa. Widening this to a single
+ * combined check would let one bad manifest entry cross between agents, which is
+ * exactly the failure this exists to prevent.
+ */
+export function assertInsideAgentRoot(p, agent) {
+    if (!isInside(p, getAgentRoot(agent))) {
+        const label = agent === 'claude' ? '~/.claude/' : '~/.codex/';
+        throw new Error(`Refusing to operate on path outside ${label}: ${p}`);
     }
 }
+/** Back-compat wrapper — the Claude path is by far the most common caller. */
+export function assertInsideClaudeDir(p) {
+    assertInsideAgentRoot(p, 'claude');
+}
+/** Which agent owns this path, or null if it belongs to neither. */
+export function agentForPath(p) {
+    if (isInside(p, getClaudeDir()))
+        return 'claude';
+    if (isInside(p, getCodexDir()))
+        return 'codex';
+    return null;
+}

package/dist/report.js

@@ -261,7 +261,10 @@ export function formatScanSummary(result) {
             const detail = issue.detail ? ` (${issue.detail})` : '';
             const tokStr = issue.tokens > 0 ? ` ~${issue.tokens.toLocaleString()} tok` : '';
             const permanent = permanentTypes.has(issue.type) ? ' \x1b[31m(permanent)\x1b[0m' : '';
-            lines.push(`  ${selected} ${i + 1}. \x1b[${color}m[${tierLabel}]\x1b[0m ${issue.type}: ${issue.name}${detail}${tokStr}${permanent}`);
+            // Tag the agent when it is not Claude Code, so a ~/.codex item is never
+            // mistaken for one under ~/.claude.
+            const agentTag = issue.agent && issue.agent !== 'claude' ? ` \x1b[36m[${issue.agent}]\x1b[0m` : '';
+            lines.push(`  ${selected} ${i + 1}. \x1b[${color}m[${tierLabel}]\x1b[0m${agentTag} ${issue.type}: ${issue.name}${detail}${tokStr}${permanent}`);
         }
     }
     // --- PLUGINS BREAKDOWN ---

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/types.d.ts

@@ -1,5 +1,6 @@
 import type { UserSurfaceEntry } from './scanner/user-surfaces.js';
-export type { UserSurfaceEntry };
+import type { AgentId } from './paths.js';
+export type { UserSurfaceEntry, AgentId };
 export interface SkillInfo {
     name: string;
     path: string;
@@ -34,9 +35,11 @@ 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;
+    /** Which agent root this issue lives under. Absent means Claude Code. */
+    agent?: AgentId;
     tier: IssueTier;
     name: string;
     detail?: string;
@@ -85,6 +88,8 @@ export interface ScanResult {
 }
 export interface ManifestEntry {
     date: string;
+    /** Which agent root `from` belongs to. Absent means Claude Code (pre-2.11 entries). */
+    agent?: AgentId;
     name: string;
     from: string;
     type: IssueType;

package/package.json

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