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

179 lines
8.7 KiB
Markdown

# 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:
```bash
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:
```bash
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`
```bash
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
```bash
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.