codeburn/docs/optimize.md
Resham Joshi b18d42d0b4
feat(optimize): flag one-hour cache writes the next request never needed (#1860)
* fix(optimize): price findings from the calls they point at

Every finding's dollar figure was its token estimate times one blended
rate: 70% of the period's spend over all input-side tokens. That rate is
close to a cache-read price, so it misprices anything that is not a cache
read. Schema findings already weight cache reads at 0.1, so their reads
were discounted twice; findings whose tokens include output were priced
as input.

A finding can now carry savingsUSD, computed from the calls it names.
Every surface reads it through findingUSD: the CLI and TUI optimize
views, the JSON report (and so the desktop Optimize page), the menubar
payload and MCP get_savings, and the --apply list. classTotals sums it,
scaled to the apply-able share for fix findings. Findings without it keep
tokensSaved times the blended rate, and any token whose session or model
has no price still falls back to that rate.

Measured now:
- low-worth-sessions: each session's real cost times its recovery fraction
- retry-heavy-capabilities: the retry turns' real cost times the fraction
- redundant-rereads, build-folder-reads: the reads at the input rate of
  their session's most-called model
- warmup-heavy: the excess cache writes at the session model's write rate
- mcp-low-coverage, mcp-project-scope: each call's charged schema tokens
  at that call model's cache-write or cache-read rate
- unused-mcp, mcp-deferral-off, mcp-alwaysload-hygiene,
  mcp-defer-threshold: the per-session schema at the input rate of the
  sessions charged

Still on the blended rate, because no calls can be named: read-edit-ratio
(reads that never happened), context-heavy-sessions, cost-outliers,
low-cache-hit-sessions, claude-md-too-long, bash-output-cap,
recurring-context and the unused agents, skills and commands.

* feat(optimize): flag one-hour cache writes the next request never needed

A one-hour prompt-cache write is billed at 1.6 times the five-minute
rate and only earns that back when the same model's cache is next used
after a pause of more than five minutes but less than an hour. Reads
refresh either TTL, so a write is judged by the first such pause after
it, not just by the very next call.

The new one-hour-cache-unused nudge walks each session per model in
time order, prices the 60% premium on every one-hour write that never
reached such a pause from the call's own model and tier, and fires at
one dollar or more. Unpriced models and five-minute writes add nothing.

* test(optimize): pin one-hour writes that later hits kept warm

Every cache hit refreshes the TTL, so a one-hour write followed by more
than an hour of steady activity and then a twenty-minute pause still
needed the hour. The detector already judges the length of the first
pause over five minutes, not its distance from the write; this test
pins that. A pause that itself runs past the hour still counts as
wasted, because the one-hour entry expires inside it either way.

Also lists one-hour-cache-unused among the measured findings.
2026-11-05 00:10:23 +01:00

8.7 KiB

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, and the block each session opens with. This is where re-reads, junk directory reads, low read:edit ratios, warmup overhead, retries, context pasted into session after session, 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

After you apply

Applying a fix is a claim, so CodeBurn checks it. Every codeburn optimize run re-measures the fixes still in place and prints them under Applied fixes, one line each:

Line Verdict Meaning
✓ unused-skills (7d ago): est. 300.0K -> measured 280.0K worked at least 70% of the estimate showed up in your sessions
~ mcp-defer-threshold (5d ago): est. 600.0K -> measured 420.0K (-30% vs estimate) partial it helped, but under its estimate
✗ bash-output-cap (6d ago): est. 41.0K -> measured 0 - did not help. Revert: codeburn act undo 3f2a1c04 no-effect no measured reduction at all
… mcp-remove (1d ago): measuring, check back after 3 days measuring too young, or the change has not taken effect in a session yet

The estimate shown is the at-apply estimate scaled to the measured window, so the two numbers are comparable. Both come from the same reconciliation codeburn act report prints — there is one set of numbers, not two — and they are measured: provider-counted usage over the post-apply window. Anything that cannot be measured (no baseline captured, a fix you reverted by hand, a correlation-only kind like guard-install) stays on the measuring line with the reason, never a claimed saving.

--format json carries the same list as appliedFixes[], and the section appears in the dashboard TUI and the desktop app.

--auto-revert

codeburn optimize --auto-revert

Off by default. It undoes exactly the fixes whose verdict is no-effect, through the same code path as codeburn act undo (backups restored, drift check applied, the revert journaled). It never touches a partial or still-measuring fix, and it never auto-reverts a claude-md-rule — those land in whatever project directory you were in, the same reason --yes skips them, so it prints the undo command and leaves the file alone.

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, cost-outliers and one-hour-cache-unused.
  • 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.

Usage

codeburn optimize                       # scan the last 30 days
codeburn optimize -p today              # today only
codeburn optimize -p week               # last 7 days
codeburn optimize --provider claude     # restrict to one provider
codeburn optimize --format json         # setup health + findings as JSON

Claude Code session population

For Claude Code, the optimize session count, the per-session findings, coaching, and model-default recommendations use user-started (main) sessions. Subagent sidechain transcripts are excluded from that population because their delegated context and delivery behavior are structurally different, and so is the re-read finding, since a subagent starts on a fresh context. Findings about how Claude uses tools (junk reads, read:edit ratio) and every spend, MCP, and configuration-overhead finding keep counting them.

More waste patterns

  • Wasted bash output (uncapped BASH_MAX_OUTPUT_LENGTH, trailing noise)
  • Cache creation overhead and junk directory reads
  • Context-heavy sessions where effective input/cache tokens swamp output
  • Possibly low-worth expensive sessions with no edit turns or repeated retries when no git/gh delivery command is observed

Ranking and repeat runs

Findings are ranked by urgency (impact weighted against observed waste) and rolled up into an A to F setup health grade. Repeat runs classify each finding as new, improving, or resolved against a 48-hour recent window.

Dashboard shortcut

You can also open it inline from the dashboard: press o when a finding count appears in the status bar, b to return.

When results get checked

The loop closes on honesty: once an applied fix is at least 3 days old, codeburn act report compares its estimated savings against what your sessions actually did, and every later codeburn optimize run lists it under Applied fixes with a plain verdict — worked, under its estimate, or did not help, with the undo command for that last case.