codeburn/docs/optimize.md

optimize

codeburn optimize scans your Claude Code sessions and your ~/.claude/ setup, reports what is costing tokens without earning them, and grades the setup A to F.

What it scans

• Session transcripts for the selected period: tool calls, per-call token usage, turn retries, per-session cost. This is where re-reads, junk directory reads, low read:edit ratios, warmup overhead, retries, and expensive or context-heavy sessions come from.
• Your configuration: ~/.claude.json, user and project settings.json / settings.local.json, .mcp.json, CLAUDE.md (including @-imports), and the skills/, agents/, commands/ directories. This is where unused MCP servers, MCP deferral gaps, ghost skills/agents/commands, the bash output cap, and oversized CLAUDE.md files come from.

Nothing is written during a scan. Only --apply writes.

The three classes

Every finding carries a class, and both the CLI and the apps group by it:

Class	Header	Meaning
fix	Fix now (apply-able)	CodeBurn can make this change for you: codeburn optimize --apply
nudge	Habits	Behavioural. Nothing to edit; the fix is how you drive the next session
keep	FYI	Informational. The cost may well be justified; decide for yourself

A finding is fix only when a plan can actually be built for that instance. The same detector can report a fix in one run and a nudge in another: mcp-deferral-off is appliable when the cause is an ENABLE_TOOL_SEARCH override in a settings file, but manual when the cause is Vertex AI policy, an outdated Claude Code, or an override that lives in your shell profile.

What --apply may write

--apply builds a plan per finding, shows you the exact files it will touch, and asks before writing. --dry-run prints the plan and stops.

Finding	File it edits
unused-mcp, mcp-low-coverage	~/.claude.json, project .mcp.json / settings.json (removes the server entry)
mcp-project-scope	moves a global server entry into the keeper project's .mcp.json
mcp-deferral-off	the settings file carrying the ENABLE_TOOL_SEARCH override
mcp-alwaysload-hygiene	the config files carrying "alwaysLoad": true
mcp-defer-threshold	the settings file carrying the auto:N threshold
unused-agents, unused-skills, unused-commands	moves the files into ~/.claude/<kind>/.archived/
bash-output-cap	appends a marker block to ~/.zshrc / ~/.bashrc
read-edit-ratio, build-folder-reads	appends a marker block to the current project's CLAUDE.md

Every write is backed up and journaled first:

codeburn act list             # every change CodeBurn has made
codeburn act undo <id>        # restore the original files
codeburn act undo --last

Undo refuses if a file changed after the apply, unless you pass --force.

The --yes CLAUDE.md guardrail

--apply --yes skips the prompt for every plan except CLAUDE.md rule blocks. Those land in the CLAUDE.md of whatever directory you happen to be in, so a blanket --yes from an unrelated directory would write advice into the wrong project. To apply one anyway, use the interactive picker or name it explicitly:

codeburn optimize --apply --only read-edit-ratio

measured vs estimated

Each finding also carries a basis, printed next to its savings and summarised in the header as N measured · M estimated:

• measured — the token number is summed from provider-counted usage on your own calls. Today that is context-heavy-sessions and cost-outliers.
• estimated — the token number comes from a model: a per-tool schema size, a per-line CLAUDE.md cost, an average read size, a recovery fraction applied to real turn tokens. A detector that mixes counted tokens with a model counts as estimated.

Sessions whose cost the provider never reported (Kiro, Cursor, some Cline sessions price from modelled token counts) are kept out of the cost-outliers peer comparison, so a modelled cost is never called an outlier against provider-reported ones. When a provider only ever estimates, the comparison falls back to those sessions and the finding reports itself as estimated.

In --format json, summary.measuredSavingsUSD is the share of summary.potentialSavingsCostUSD that comes from measured findings.

Reading the health grade

Health starts at 100 and loses points per finding: 15 for a high-impact one, 7 for medium, 3 for low. The total penalty is capped at 80, so a long tail of small findings cannot sink the score to zero on its own. The grade is a band over that score:

Grade	Score
A	90-100
B	75-89
C	55-74
D	30-54
F	below 30

The grade rates your setup, not your spending: an expensive month with a clean configuration still scores an A.