# 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:

```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
```

## 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.