Epic: opt-in acting layer (apply fixes, session guard, measured savings)

[iamtoruk]

Epic: opt-in acting layer (apply fixes, session guard, measured savings)

Motivation

CodeBurn currently sees waste and prints the fix, but acting on it is manual. On a real 30-day dataset (2.3k sessions) optimize flagged roughly 20% of spend as avoidable. The composition is the important part:

• ~12% of the flagged value is config hygiene (MCP servers with low tool coverage, servers loaded in projects that never call them, unused skills/agents, oversized bash output caps, missing CLAUDE.md rules)
• ~88% is behavioral: runaway low-yield sessions, context-heavy sessions, cost outliers. yield on the same dataset marked ~30% of a week's spend as sessions that never shipped.

So an acting layer must do two different jobs: execute config fixes safely, and be present at session time to catch the expensive behavioral patterns. Neither requires touching the request path.

Principles (non-negotiable)

1. The core stays a passive analyzer. All acting code lives in clearly separated modules and commands. Nothing here runs unless the user explicitly invokes or installs it.
2. Off by default. No hook, no config edit, no interception happens without an explicit opt-in command.
3. Every action is journaled and undoable. Any file CodeBurn modifies is backed up first. codeburn act undo restores it. No exceptions.
4. Dry-run first. Every apply path shows exactly what will change before it changes.
5. Measured, not estimated. Applied fixes get before/after measurement so optimize can report realized savings next to estimates.
6. No request-path proxy in this epic. Per-turn model routing and tool-def interception are explicitly out of scope (see Non-goals).

Architecture overview

Three mechanism classes, in increasing risk order:

• Class A, config edits: executing the fixes optimize already prints (MCP scope changes, archiving unused capabilities, CLAUDE.md rule blocks, shell config). Pure file edits with backup and undo.
• Class B, session-time hooks: Claude Code natively supports SessionStart / PreToolUse / Stop hooks and a statusline. A codeburn guard hook pack covers budget caps, session openers for flagged projects, and end-of-session yield nudges, all local and removable.
• Class C, request path: not built here. If per-turn routing is ever justified by data, it arrives as a separate opt-in binary after a dedicated design review.

New surface:

codeburn act list            # journal of applied actions
codeburn act undo <id|--last>
codeburn act report          # realized vs estimated savings
codeburn optimize --apply    # interactive apply of class-A fixes
codeburn guard install|uninstall|status   # class-B hook pack

Sub-issues

• Action journal, backups, and undo core (codeburn act) #603 Action journal, backups, and undo core (codeburn act)
• codeburn optimize --apply: execute config-class fixes with undo #604 codeburn optimize --apply for config-class fixes
• codeburn guard: opt-in session-time hook pack for Claude Code #605 codeburn guard: session-time hook pack for Claude Code
• Realized savings: measure applied fixes (codeburn act report) #606 Realized savings measurement (codeburn act report)
• Model/effort default recommendations from compare data (design-gated) #607 Model/effort defaults from compare data (design-gated, do not start before Action journal, backups, and undo core (codeburn act) #603 and codeburn optimize --apply: execute config-class fixes with undo #604 land)

Dependency order: #603 first, then #604 and #605 in parallel, #606 after #604, #607 last and only after a design review on the issue itself.

Non-goals

• No local proxy, no MITM of provider traffic, no per-turn model rewriting. A community prototype exists for proxy-based routing and tool-def deferral; evaluating it is a separate future track with its own issue, gated on captured evidence (pre-turn classification accuracy, cache-hit impact, auth mode). Not part of this epic.
• No tool-def stripping. Claude Code already ships native deferred tool loading; where heavy MCP load is detected, the correct action is config-level (scope or remove servers), not request rewriting.
• Nothing on by default, no telemetry, no network calls beyond what the analyzer already does.

Epic acceptance

• A user can go from optimize findings to applied fixes, with undo, in under a minute, without leaving the CLI.
• A user can opt a project into the session guard and see a budget warning fire in a real session, then cleanly uninstall it leaving settings byte-identical to the pre-install backup.
• optimize output distinguishes estimated savings from realized savings on applied items.
• Core commands (usage, optimize without --apply, context, yield, compare) behave identically for users who never opt in.