agent-cleaner-skills

agent-cleaner — Codex skills and MCP server slimming

When the user wants to slim Codex skills or MCP servers, follow the same flow: enumerate → suggest → confirm → disable. The CLI exposes parallel skills and mcp command trees on Codex (subagents are Claude Code-only).

1. Locate the bundled CLI

Prefer ${AGENT_CLEANER_CLI} if set. Otherwise locate the newest installed bundle:

find "${CODEX_HOME:-$HOME/.codex}/plugins/cache/local/agent-cleaner" -path '*/lib/agent-cleaner.mjs' -type f 2>/dev/null | sort | tail -1

If that finds nothing, check the current repository path:

test -f plugins/codex/lib/agent-cleaner.mjs && pwd

Always invoke via node <abs-path> and always pass --host=codex.

2. Listing and suggesting

node "<abs-path>/agent-cleaner.mjs" --host=codex skills suggest --json

The output is a JSON array of suggestions, each with id, name, source, reason (never-used | stale), confidence (high | medium | low), details.

If the user wants to see all skills, use skills list --json.

3. Confirm with the user

Show the suggestion list as a compact table with id, reason, and confidence. Never disable without explicit user confirmation.

If the user wants to adjust the staleness threshold, mention --unused-for=60d (or 2w, 3m, 1y) or persist a default in ~/.agent-cleaner/config.json:

{ "unusedForDays": 60 }

4. Disable

Either pass specific ids:

node "<abs-path>/agent-cleaner.mjs" --host=codex skills disable user:codex:lark-mail plugin:gmail@openai-curated:gmail --yes

Or apply all current suggestions in one shot:

node "<abs-path>/agent-cleaner.mjs" --host=codex skills disable --all-suggested --yes

After disable succeeds, tell the user: "Disabled N skills. Restart Codex or start a new Codex session for the change to take effect."

5. Other operations

• skills enable <id...> — undo a disable.
• skills status [--json] — list currently-disabled skills and detect/auto-reapply any that an upstream plugin or skill update may have restored.
• skills list --json — full inventory with lastUsed and callCount.

6. MCP servers

The same verbs apply with mcp instead of skills. Codex MCP servers live as [mcp_servers.NAME] blocks in ~/.codex/config.toml:

node "<abs-path>/agent-cleaner.mjs" --host=codex mcp suggest --json
node "<abs-path>/agent-cleaner.mjs" --host=codex mcp disable mcp:user:codex:linear --yes
node "<abs-path>/agent-cleaner.mjs" --host=codex mcp disable --all-suggested --yes

Usage is detected from mcp__<server>__<tool> tool calls in Codex session transcripts under ~/.codex/sessions/.

Constraints

• Codex system skills under ~/.codex/skills/.system cannot be disabled.
• Skills disable: mv SKILL.md SKILL.md.agent-cleaner-disabled. MCP disable: the [mcp_servers.NAME] block is spliced out of config.toml and the original lines are stashed in state. enable reverses both.
• State is kept at ~/.agent-cleaner/state-codex.json.