context-opti

A Claude Code plugin that audits how much of a project's context budget goes to things that load automatically — before you decide what to trim.

The problem it's built for

Every Claude Code session pays a fixed cost before you type a word: the CLAUDE.md chain, skill metadata, whatever .claude/ carries. That cost grows quietly. A handoff doc doubles, a second status file gets added next to the first one nobody deleted, and six months later nobody knows which number in the context budget actually matters.

Most fixes for this go straight to editing: shrink the file, split it, summarize it. context-opti doesn't. It measures first, in a separate read-only pass, and shows you the numbers before anything changes.

What it actually does

Four canonical files count as "loads every session": CLAUDE.md, CLAUDE.local.md, and their .claude/ equivalents. Everything else — nested CLAUDE.md files, skill bodies, large docs — loads on demand, and the audit reports those separately, because a 300 KB file you open once a month isn't the same cost as 6 KB that loads on every single message.

The script itself is a plain PowerShell file, not the model guessing sizes from memory. It walks the project tree once, skips .git, node_modules, build output, and binaries, and never follows a symlink out of the project root. Line counts stop the moment a file crosses the "this is large" threshold — no reason to read the rest of a 400 KB file just to confirm it's large. Every section of output is capped, with a hidden-count line for anything cut, because the audit's own output becomes context too, and an audit that costs more than it saves has missed the point.

Duplicate status/handoff files come back as a flat, capped list by filename pattern. No scoring, no "confidence." Two files named STATUS-oct.md and STATUS-nov.md are for a human to glance at, not for a heuristic to decide about.

Why it's built this way

A quick context-optimizer script is easy to write badly in ways that don't show up until they've already cost you something:

• It reads the files it's trying to save you from reading. A script that opens every candidate in full to summarize it has already spent the tokens it claims to save. This one reads locally to count lines and headers, and never puts a file body in its own output.
• It "cleans up" by deleting. History is data. context-opti never deletes — it archives, and only after you approve the exact file list by name.
• It runs on its own. This one sets disable-model-invocation: true in its manifest, so the harness — not a promise in the skill's prose — blocks it from firing itself. It only runs when you call it.
• It writes first and asks later, or doesn't ask a second time. Every write in this skill is gated: full audit and report first, explicit per-item approval, then — immediately before touching a specific file — a fresh git status check on that exact path. If you'd already changed it since the baseline, the skill stops and asks again by name instead of overwriting silently.
• It treats "smaller" as the goal. Token savings that cost you a fact, a caveat, or a hedge in the compacted file are a failed run, not a successful one, regardless of what the before/after byte count says.

None of this is a claim about any specific tool someone else has published — I haven't audited what else is out there closely enough to name names and grade them. It's a description of the failure modes I designed around because they were the ones I could see happening to my own CLAUDE.md.

Structure

.claude-plugin/plugin.json          plugin manifest
.claude-plugin/marketplace.json     self-listing, for /plugin marketplace add
skills/context-opti/SKILL.md        the workflow: Phase 0-5, hard rules
skills/context-opti/scripts/audit_context.ps1   the read-only audit script

Install

In an interactive Claude Code session, run /plugin with no arguments to see what your CLI version supports for adding a marketplace and installing from it — the exact subcommand names have moved between versions, so I'm not going to print a command here I can't verify against your build.

Scope

The skill only audits by default. Writing, moving, or deleting a file happens only after you approve an explicit plan, item by item, and it never runs git add, commit, or push on its own. Full rules in skills/context-opti/SKILL.md.

License

MIT — see LICENSE.