Feature: --exclude-codex flag or exclusive --root mode for OpenCode-first users

[its-How]

Thanks for skill-cleaner — it's a well-designed read-only diagnostic for Codex skill inventories, and the budget calculation (mirroring core-skills/src/render.rs 2% rule) is genuinely useful.

I'd like to request a feature that would extend its usefulness to OpenCode-first users.

Context

I maintain a multi-runtime setup where OpenCode is the primary runtime and Codex is secondary. My OpenCode skills live in ~/.agents/skills/ and my Codex skills in ~/.codex/skills/. I wanted to use skill-cleaner to audit ONLY my OpenCode skills, but discovered that --root is additive, not replacement.

Evidence

Looking at skills/skill-cleaner/scripts/skill-cleaner.ts, the discoverRoots() function (line 507) always appends the default Codex paths in addition to any --root arguments:

• path.join(home, ".codex/skills") (line 510)
• path.join(home, ".codex/plugins/cache") (line 511)
• path.join(home, "Projects/agent-scripts/skills") (line 512)
• ...extraRoots.map(expandHome) (line 513, the --root args)

There's no flag to disable the default ~/.codex/ scan. --root ADDS paths but does not REPLACE them.

I tested this with --root <temp-opencode-root> --no-live --no-logs. The report enumerated 59 skills: 4 from my temp OpenCode root + 55 from my real ~/.codex/skills/ and ~/.codex/plugins/cache/. For an OpenCode-first user, the 55 Codex skills are noise that can't be filtered out.

Proposed fix

Either of these would resolve it:

1. --exclude-codex flag: skips the default ~/.codex/skills/ and ~/.codex/plugins/cache/ scans, using only --root paths.
2. Exclusive --root mode: when --root is specified, it replaces default paths instead of appending. (Possibly behind a --root-only flag to preserve current behavior for existing users.)

Option 1 is probably safer for backward compatibility.

Use case

OpenCode-first users (and users who want to audit an isolated skill set without their full Codex installation mixed in) would benefit. Currently the tool is Codex-only in practice, despite --root suggesting otherwise.

What I'm not asking for

• Not asking for OpenCode-specific path awareness (the tool can stay runtime-neutral for --root paths)
• Not asking for OpenCode budget calculation (Codex's 2% rule is Codex-specific; OpenCode users just want the inventory/duplicate/unused features)

Happy to draft a PR if this feature request is welcome. Thanks for considering.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 27, 2026, 10:59 PM ET / 02:59 UTC.

Summary
Keep open: current main still makes --root additive and has no --exclude-codex or exclusive-root option. This is a useful but new CLI behavior request, so it needs maintainer choice on the public flag semantics before implementation.

Reproducibility: not applicable. as a feature request. Source inspection gives high confidence that current --root handling is additive because discoverRoots() includes default roots before appending extraRoots.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Share version, platform, channel/provider, and relevant config details.

Next step
A maintainer should choose the public CLI shape before implementation because both proposed solutions are viable and affect option semantics.

Review details

Best possible solution:

Add a backward-compatible explicit mode such as --root-only that limits filesystem discovery to supplied roots while preserving existing additive --root behavior by default.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a feature request. Source inspection gives high confidence that current --root handling is additive because discoverRoots() includes default roots before appending extraRoots.

Is this the best way to solve the issue?

Unclear until maintainers pick the CLI contract. The narrowest compatibility-safe path appears to be a new opt-in exclusive-root flag rather than changing existing --root semantics.

AGENTS.md: not found in the target repository.

Remaining risk / open question:

• Changing the existing --root option from additive to replacement could break users who rely on additive scans; an opt-in flag is safer unless maintainers choose a compatibility break.

Codex review notes: model internal, reasoning high; reviewed against ea989d661163.

Label changes

Label changes:

• add P3: The request is a low-risk CLI ergonomics improvement for a diagnostic skill rather than an urgent runtime bug.
• add impact:other: The issue affects skill-cleaner audit usefulness for users who need isolated non-Codex skill inventories, which is outside the specific impact taxonomy.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P3: The request is a low-risk CLI ergonomics improvement for a diagnostic skill rather than an urgent runtime bug.
• impact:other: The issue affects skill-cleaner audit usefulness for users who need isolated non-Codex skill inventories, which is outside the specific impact taxonomy.

Evidence reviewed

Acceptance criteria:

• node --test --experimental-strip-types skills/skill-cleaner/scripts/skill-cleaner.test.ts

What I checked:

• No target AGENTS or VISION policy: No AGENTS.md, VISION.md, taxonomy.yaml, or qa/maturity-scores.yaml exists under the target repository root.
• Current argument parsing: Current main only collects --root values into extraRoots; there is no parsed --exclude-codex, --root-only, or equivalent option. (skills/skill-cleaner/scripts/skill-cleaner.ts:85, ea989d661163)
• Current root discovery behavior: discoverRoots() includes default Codex and repository roots before appending ...extraRoots.map(expandHome), so user-provided roots do not replace defaults. (skills/skill-cleaner/scripts/skill-cleaner.ts:507, ea989d661163)
• Skill documentation describes additive roots: The skill notes say normal Codex/plugin/repo roots are scanned by default and extra folders are included only with --root <path>, with no exclusive-root mode documented. (skills/skill-cleaner/SKILL.md:49, ea989d661163)
• No existing implementation or canonical item: Repository and GitHub searches found this issue as the only same-topic item for exclude-codex, root-only, OpenCode, or skill-cleaner root filtering; inspected search hits outside this issue were unrelated.
• History and ownership: Git blame and log show the relevant root discovery and CLI option code was introduced in the original skill-cleaner commit and later maintained in adjacent skill-cleaner commits by Peter Steinberger. (skills/skill-cleaner/scripts/skill-cleaner.ts:507, c2da3dfa9727)

Likely related people:

• steipete: The root discovery, --root parsing, and later skill-cleaner maintenance history are all in Peter Steinberger commits for the central files. (role: feature introducer and recent area contributor; confidence: high; commits: c2da3dfa9727, 4bb184e96249, 448cfa972336; files: skills/skill-cleaner/scripts/skill-cleaner.ts, skills/skill-cleaner/SKILL.md, skills/skill-cleaner/scripts/skill-cleaner.test.ts)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.