claude-slim 2.10.0 → 2.12.0

package/README.md

@@ -165,6 +165,7 @@ 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
+npx claude-slim update                   # Run the upgrade for this install method
 npx claude-slim restore                  # Undo
 npx claude-slim report                   # Show savings from last clean
 ```
@@ -202,7 +203,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.
+- **`~/.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.
@@ -247,18 +248,12 @@ Token counts come from [js-tiktoken](https://github.com/nicolo-ribaudo/js-tiktok
 
 ---
 
-## v2.10.0 — What's new
+## v2.12.0 — What's new
 
-Codex support, scoped to what Codex can actually be asked.
+- **`claude-slim update`** — runs the upgrade command for however this copy was installed, after showing it and asking. `--dry-run` to preview, `--yes` to skip the prompt. Plugin installs get the marketplace refresh first, then the qualified `claude-slim@claude-slim` id, and are reminded that a restart is needed. npx and source checkouts run nothing and say why — npx already resolves the latest every invocation, and pulling your own repository is not claude-slim's to do.
+- **This corrects v2.9.0's reasoning.** That release stopped at detection, arguing updating belonged to the package manager. Half held: claude-slim must not write into a directory `claude plugin` owns. The other half did not — invoking the package manager is something this tool already does during cleanup (`claude plugin disable`), so refusing to here was inconsistent. It still writes nothing itself.
 
-- **`~/.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/`.
-
-- **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).
+Tests: 374 → 392 (+18), pinning the safety properties — every argv a fixed literal, no shell metacharacters, executable only ever `claude` or `npm`, and a refusal to run unattended with no TTY and no `--yes`.
 
 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,
@@ -85,6 +88,7 @@ export async function cleanIssues(issues) {
                 await rename(issue.path, dest);
                 const entry = {
                     date: new Date().toISOString(),
+                    agent,
                     name: issue.name,
                     from: issue.path,
                     type: issue.type,
@@ -108,6 +112,7 @@ export async function cleanIssues(issues) {
                 }
                 const entry = {
                     date: new Date().toISOString(),
+                    agent,
                     name: issue.name,
                     from: issue.path,
                     type: issue.type,
@@ -131,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,
@@ -210,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})`);
     }
@@ -220,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
@@ -239,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,8 +11,10 @@ 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 { confirmDecision, planUpdate, renderStep, runUpdate } from './update-run.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'));
@@ -100,6 +102,81 @@ program
         console.log(`\n  \x1b[32m✓\x1b[0m claude-slim ${result.installed} is up to date.\n`);
     }
 });
+// --- update ---
+// Detection lives in `check-update`; this runs the command that detection
+// identified. claude-slim still never writes into a package manager's
+// directories itself — it invokes the manager, the same way cleanup already
+// invokes `claude plugin disable`.
+program
+    .command('update')
+    .description('Run the upgrade command for however this copy was installed')
+    .option('--yes', 'Skip the confirmation prompt')
+    .option('--dry-run', 'Show the commands without running them')
+    .action(async (opts) => {
+    const result = await checkForUpdate({ force: true });
+    const plan = planUpdate(result.installMethod);
+    console.log('');
+    console.log(`  Installed: ${result.installed}   Latest: ${result.latest ?? 'unknown'}`);
+    console.log(`  Install method: ${result.installMethod}`);
+    console.log('');
+    if (result.latest === null) {
+        console.log('  Could not reach the npm registry, so there is nothing to compare against.');
+        console.log('');
+        process.exitCode = 1;
+        return;
+    }
+    if (!result.outdated) {
+        console.log('  \x1b[32m✓\x1b[0m Already up to date.\n');
+        return;
+    }
+    if (!plan.runnable) {
+        console.log(`  ${plan.guidance}\n`);
+        return;
+    }
+    console.log('  Will run:');
+    for (const step of plan.steps)
+        console.log(`    ${renderStep(step)}`);
+    console.log('');
+    if (opts.dryRun) {
+        console.log('  \x1b[90mDry run — nothing was executed.\x1b[0m\n');
+        return;
+    }
+    const gate = confirmDecision(opts, Boolean(process.stdin.isTTY));
+    if (gate === 'refuse') {
+        console.error('  Refusing to run unattended. Re-run with --yes to confirm.\n');
+        process.exitCode = 1;
+        return;
+    }
+    if (gate === 'prompt') {
+        const answer = await askUser('  Proceed? [y/N] ');
+        if (!/^y(es)?$/i.test(answer)) {
+            console.log('  Cancelled.\n');
+            return;
+        }
+        console.log('');
+    }
+    const results = await runUpdate(plan);
+    for (const r of results) {
+        const mark = r.ok ? '\x1b[32m✓\x1b[0m' : '\x1b[31m✗\x1b[0m';
+        console.log(`  ${mark} ${renderStep(r.step)}`);
+        if (r.output)
+            console.log(r.output.split('\n').map((l) => `      ${l}`).join('\n'));
+    }
+    const failed = results.find((r) => !r.ok);
+    console.log('');
+    if (failed) {
+        console.log('  Update did not complete. Run the commands above manually to see the full error.\n');
+        process.exitCode = 1;
+    }
+    else if (result.installMethod === 'plugin') {
+        // The new version is on disk but the running session still holds the old
+        // one — without saying so, users update, re-run, and see identical output.
+        console.log('  \x1b[33m!\x1b[0m Restart Claude Code for the update to take effect.\n');
+    }
+    else {
+        console.log('  \x1b[32m✓\x1b[0m Updated.\n');
+    }
+});
 // --- clean ---
 program
     .command('clean')
@@ -108,12 +185,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 ---
@@ -269,12 +348,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

@@ -41,6 +41,11 @@ export declare function isCodexInstalled(): Promise<boolean>;
  * back to the flat estimate.
  */
 export declare function parseTomlDescription(content: string): string | null;
-export declare function scanCodex(): Promise<CodexScanResult | 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

@@ -60,7 +60,7 @@ export function parseTomlDescription(content) {
     const unescaped = single[1].replace(/\\"/g, '"').replace(/\\\\/g, '\\').trim();
     return unescaped || null;
 }
-async function scanLocalSkills() {
+async function scanLocalSkills(contents) {
     const dir = join(getCodexDir(), 'skills');
     const entries = await safeReaddir(dir);
     const results = [];
@@ -77,6 +77,7 @@ async function scanLocalSkills() {
         const content = await safeReadFile(md);
         if (content === null)
             continue;
+        contents?.set(md, content);
         results.push({
             name: entry,
             path: skillDir,
@@ -161,11 +162,16 @@ async function scanAgents() {
     }
     return results;
 }
-export async function scanCodex() {
+/**
+ * @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(),
+        scanLocalSkills(contents),
         scanPluginSkills(),
         scanAgents(),
     ]);

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/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;
@@ -37,6 +38,8 @@ 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' | '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/dist/update-run.d.ts

@@ -0,0 +1,40 @@
+import type { InstallMethod } from './update-check.js';
+export interface UpdateStep {
+    file: string;
+    args: string[];
+}
+export interface UpdatePlan {
+    /** false when there is nothing to execute — see `guidance`. */
+    runnable: boolean;
+    steps: UpdateStep[];
+    /** Why nothing runs, for the methods where that is the correct answer. */
+    guidance?: string;
+}
+export declare function planUpdate(method: InstallMethod): UpdatePlan;
+/** Human-readable rendering of a step, matching what the user would type. */
+export declare function renderStep(step: UpdateStep): string;
+export interface StepResult {
+    step: UpdateStep;
+    ok: boolean;
+    output: string;
+}
+/**
+ * Run the plan's steps in order, stopping at the first failure.
+ *
+ * Sequential rather than parallel, and halting on error, because step 2 depends
+ * on step 1 having refreshed the marketplace — running it against a stale
+ * manifest would report success while changing nothing.
+ */
+export declare function runUpdate(plan: UpdatePlan): Promise<StepResult[]>;
+export type ConfirmDecision = 'run' | 'prompt' | 'refuse';
+/**
+ * Decide how to gate an update that will modify the user's install.
+ *
+ * Refusing when there is no TTY is the important case: piped into a script or a
+ * CI job, there is nobody to answer the prompt, and silently proceeding would
+ * mean a tool that changes an installation without anyone agreeing to it.
+ * `--yes` is how you say so deliberately.
+ */
+export declare function confirmDecision(opts: {
+    yes?: boolean;
+}, isTTY: boolean): ConfirmDecision;

package/dist/update-run.js

@@ -0,0 +1,101 @@
+import { execFile } from 'node:child_process';
+// Running the upgrade.
+//
+// v2.9.0 shipped detection only, on the reasoning that updating is the package
+// manager's job. Half of that was right and half was not. Writing into the
+// plugin directory ourselves would indeed corrupt an install — but *invoking*
+// the package manager is something this tool already does elsewhere
+// (`claude plugin disable` during unused-plugin cleanup). Refusing to invoke it
+// here was inconsistent, not principled.
+//
+// So: still never write to those directories directly. Just run the command the
+// user would have typed, after showing it to them.
+//
+// Every argv below is a fixed literal. Nothing from the environment, the
+// manifest, or user input is interpolated, and execFile never routes through a
+// shell — so there is no argument-injection surface to guard.
+const STEP_TIMEOUT_MS = 180_000;
+export function planUpdate(method) {
+    switch (method) {
+        case 'plugin':
+            return {
+                runnable: true,
+                steps: [
+                    // Refresh the marketplace first; otherwise `plugin update` compares
+                    // against a stale manifest and reports "already up to date".
+                    { file: 'claude', args: ['plugin', 'marketplace', 'update', 'claude-slim'] },
+                    // The qualified id is required: the bare name fails with
+                    // `Plugin "claude-slim" not found` when a marketplace shares its name.
+                    { file: 'claude', args: ['plugin', 'update', 'claude-slim@claude-slim'] },
+                ],
+            };
+        case 'global':
+            return {
+                runnable: true,
+                steps: [{ file: 'npm', args: ['install', '-g', 'claude-slim@latest'] }],
+            };
+        case 'npx':
+            return {
+                runnable: false,
+                steps: [],
+                guidance: 'npx resolves the latest version on every invocation, so there is nothing to update. ' +
+                    'If a stale copy is cached, run `npx claude-slim@latest` once to refresh it.',
+            };
+        case 'source':
+            return {
+                runnable: false,
+                steps: [],
+                guidance: 'This is a source checkout. Updating it means pulling your own repository, ' +
+                    'which claude-slim will not do on your behalf — run `git pull && npm install` yourself.',
+            };
+        default:
+            return {
+                runnable: false,
+                steps: [],
+                guidance: 'Could not tell how this copy was installed, so no upgrade command can be chosen safely. ' +
+                    'Update it the same way you installed it.',
+            };
+    }
+}
+/** Human-readable rendering of a step, matching what the user would type. */
+export function renderStep(step) {
+    return [step.file, ...step.args].join(' ');
+}
+function runStep(step) {
+    return new Promise((resolve) => {
+        execFile(step.file, step.args, { timeout: STEP_TIMEOUT_MS }, (err, stdout, stderr) => {
+            const output = [stdout, stderr].map((s) => s?.trim()).filter(Boolean).join('\n');
+            resolve({ step, ok: !err, output: err ? `${err.message}${output ? `\n${output}` : ''}` : output });
+        });
+    });
+}
+/**
+ * Run the plan's steps in order, stopping at the first failure.
+ *
+ * Sequential rather than parallel, and halting on error, because step 2 depends
+ * on step 1 having refreshed the marketplace — running it against a stale
+ * manifest would report success while changing nothing.
+ */
+export async function runUpdate(plan) {
+    const results = [];
+    for (const step of plan.steps) {
+        const result = await runStep(step);
+        results.push(result);
+        if (!result.ok)
+            break;
+    }
+    return results;
+}
+/**
+ * Decide how to gate an update that will modify the user's install.
+ *
+ * Refusing when there is no TTY is the important case: piped into a script or a
+ * CI job, there is nobody to answer the prompt, and silently proceeding would
+ * mean a tool that changes an installation without anyone agreeing to it.
+ * `--yes` is how you say so deliberately.
+ */
+export function confirmDecision(opts, isTTY) {
+    if (opts.yes)
+        return 'run';
+    return isTTY ? 'prompt' : 'refuse';
+}

package/package.json

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