mirror of
https://github.com/AgentSeal/codeburn.git
synced 2026-08-23 07:25:16 +00:00
6267c49c25
Adds docs/optimize.md (what optimize scans, the three classes, the exact files --apply may touch plus undo, measured vs estimated, the health grade bands, the --yes CLAUDE.md guardrail), links it from the README waste section, and corrects the detector count in docs/architecture.md (14 -> 19).
104 lines
4.8 KiB
Markdown
104 lines
4.8 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. 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.
|