CLAUDE.md hot-path cost attribution with section-level recommendations

[willwashburn]

Context

Prism (jakeefr/prism) validates this as the single highest-leverage waste-finder in a Claude Code project: CLAUDE.md rides in every turn's cached context, so a bloated CLAUDE.md silently taxes every session in the repo forever. Their real-data examples (from the README):

• "6738% CLAUDE.md re-read cost in one session: a 237-line file being re-read on every tool call"
• "CLAUDE.md re-reads consumed 480% of total session tokens"

Prism's mechanism is a proxy: reread_cost = tool_call_count × claude_md_size_tokens (analyzer.py:173). It never touches real cacheRead values. The shock ratios are (count × size) / session_incremental_tokens, meant to alarm, not to be precise.

Burn can do this correctly because the ledger already carries real per-turn cacheRead values.

Scope

One file (plus nested variants): the project's CLAUDE.md at repo root. Also detect nested .claude/CLAUDE.md or scoped src/**/CLAUDE.md files Claude Code loads hierarchically.

Mechanism

Cost attribution

At session start, resolve the active CLAUDE.md set from cwd / project root.
Measure byte length of each file; estimate tokens (bytes/4 heuristic, or tiktoken cl100k if the dep cost is acceptable).

For each turn T in the session:
  share_T = claude_md_tokens / (claude_md_tokens + tool_defs_tokens + conversation_tokens_T)
  attributed_tokens_T = usage.cacheRead_T × share_T
  attributed_cost_T   = attributed_tokens_T × cache_read_price(model)

session_claude_md_cost = Σ attributed_cost_T

• tool_defs_tokens — sum of the registered tools' schema tokens. Approximate once per session from the Claude Code client version or derive from the session JSONL if exposed; otherwise treat as a fixed constant per Claude Code minor version and measure once.
• conversation_tokens_T — back-compute from usage.input - cacheCreate - cacheRead plus the running prefix. Rough is fine; we're computing a share, not a precise boundary.
• Accounts for cache-read pricing being ~10% of fresh-input price (prism doesn't — they multiply tokens by tool-call count as if every read was fresh).

Section ranking

Unlike prism's zone heuristic (top 20%, mid 20-75%, bottom 25% at advisor.py:234-235), parse CLAUDE.md by markdown heading structure:

• # Top-level / ## Section / ### Subsection — each heading begins a section.
• Capture each section's line range, heading text, and token count.
• Compute per-section cost as (section_tokens / total_claude_md_tokens) × session_claude_md_cost.

No keyword classification (prism does tone|style|personality regex — too fragile). Rank purely by cost. The section content is what the user judges, not a classifier-assigned category.

CLI surface

burn claude-md [--project <path>] [--since 7d]
# Prints:
#   CLAUDE.md at /Users/will/Projects/foo (412 lines, ~3.1k tokens)
#   Cost per session:   avg $0.18, p95 $0.34
#   Cost last 7 days:   $4.12 across 23 sessions
#
#   Sections ranked by cost:
#     lines  12- 47  ## Architecture              1,820 tok  $0.11/session
#     lines  48- 89  ## Testing conventions         890 tok  $0.05/session
#     lines  90-148  ## Tone and personality notes  410 tok  $0.02/session   <- consider trimming
#     …

burn claude-md advise [--project <path>]
# Emits a unified diff of suggested TRIM / RESTRUCTURE hunks with
# per-recommendation projected-savings-per-session and savings-over-last-N-sessions.
# Does NOT write to the file. User applies manually.

burn claude-md --json   # programmatic

Explicitly no --apply flag. Unlike prism's advise --apply, burn never mutates files.

Acceptance

• Attribution math: on a fixture session with a known CLAUDE.md and known cacheRead values, burn claude-md reports a per-turn attributed cost within ±10% of a hand-computed baseline.
• Section parsing correctly handles: top-level text before the first heading (treated as a "preamble" section), nested headings (rolled up to their parent level for ranking), and files with no headings (reported as a single section with a note).
• Cross-session view: burn claude-md --since 7d aggregates across sessions for the same projectKey (depends on Reader infrastructure: incremental cursors and git-canonical project keys #4's git canonicalization).
• advise output is applyable by hand: line ranges match the user's current file (run against HEAD, not a stale snapshot).
• If CLAUDE.md has changed during the reporting window, attribution uses the CLAUDE.md at the time of each session, not the current version. (Read via git log if the file is tracked; fall back to current file with a warning otherwise.)

Depends on

• Reader infrastructure: incremental cursors and git-canonical project keys #4 (git-canonical projectKey) for cross-session rollup.
• Nothing else strictly blocking. Can land before burn waste: per-tool-call and per-file spend attribution #3 (burn waste) — this is the most user-visible waste finder.

Unblocks

The biggest concrete "switch a choice, save spend" answer for the meta-goal. Higher leverage than model-switching because CLAUDE.md savings compound across every future session in the repo.

Out of scope

• Automated CLAUDE.md rewriting (advise --apply equivalent) — deliberate; burn recommends, doesn't mutate.
• Adherence / "Mr. Tinkleberry" detection — prism does this with hand-coded per-rule checkers (analyzer.py:548+). Narrow and doesn't scale. See Design: outcome / quality signal for 'same output, less spend' comparisons #6.

[willwashburn]

Math improvement from opencode-tokenscope (plugin/tokenscope-lib/context.ts:303-354):

The per-turn rolling-share approach in this issue's spec —

share_T = claude_md_tokens / (claude_md + tool_defs + conversation_tokens_T)

— requires estimating tool_defs_tokens and re-computing per turn. Tokenscope uses a cleaner anchor: the session's first cache_write value is the ground-truth size of the initial cached prefix (system prompt + tool defs + env + project tree + CLAUDE.md). Real number from the API, not an estimate.

Refined spec:

cachedContextAtStart = firstCacheWriteTokens(session)   // measured
claude_md_tokens     = tokenize(CLAUDE.md file)          // measured
claude_md_share      = claude_md_tokens / cachedContextAtStart

attributed_tokens  = Σ (cacheRead_T × claude_md_share)
attributed_cost    = attributed_tokens × cache_read_price

Two measured numbers, one division, computed once per session. Assumes claude_md_share is stable through the session (no mid-session CLAUDE.md edits) — detectable if not.

Universal: applies to Claude Code (CLAUDE.md) and OpenCode (AGENTS.md) alike. Same cache_write anchor, just a different file to tokenize.

Separately: tokenscope also estimates per-tool schema costs by analyzing argument complexity in observed calls (context.ts:359+), which is a better approach than a flat ~350 tokens/tool. Worth folding in as the implementation for toolDefTokens when we still need it (for non-CLAUDE.md analyses).

Updating the acceptance criteria implicitly: the attribution math should reconcile against firstCacheWrite at session start, not against per-turn rolling context.

[willwashburn]

Extension after #33 (content sidecar).

The cacheRead-share math in this issue stays primary — it answers "how much does CLAUDE.md cost to keep in context." Content sidecar unlocks a complementary second analysis: are your CLAUDE.md rules actually being followed?

Prism's approach to this (prism/analyzer.py:548+) was rejected as unscalable because it hand-coded per-rule checkers. With stored assistant responses, a more general approach is possible: match rule text against response behavior.

Example rules from a typical CLAUDE.md:

• "Never use any in TypeScript" → grep assistant tool_uses (Edit, Write) for : any insertions after this rule's introduction.
• "Always run bun test after TypeScript changes" → check for a Bash tool call with bun test command after assistant touched any .ts file.
• "Prefer functional components in React" → grep new JSX for class.*extends.*Component.

Mechanism: rules extract to (pattern, check) pairs at CLAUDE.md-parse time; burn claude-md adherence runs each check across the session's assistant responses and tool calls; reports violations as a quality signal.

Relationship to #6

This can feed into the outcome-inference classifier (#6) as an additional axis. A session that ran without rule violations gets higher-confidence completed; one with violations gets completed (low) or errored.

Scope for this issue

Leave #10 scoped to cost attribution (the cacheRead-share math) for the MVP. Add adherence checking as a separate follow-up issue once the cost-attribution half ships and we have real data to validate rules against. Note here so the follow-up doesn't get lost.

Content dependency

Requires content.store=full. In hash-only mode, adherence checking is unavailable — cost attribution still works.

[willwashburn]

Complementary static-cost analysis from codeburn (src/context-budget.ts:1-150).

What codeburn does differently

This issue is scoped to dynamic hot-path analysis — attributing CLAUDE.md's share of cacheRead across actual session turns. Codeburn's context-budget.ts measures the complementary thing: static setup cost of what loads into context before the first API call.

// codeburn's estimate
{
  systemBase: 10_400,                      // Claude Code's base system prompt
  mcpTools:   { count: N, tokens: N*400 }, // estimated 400 tokens per MCP tool
  skills:     { count: M, tokens: M*80 },  // estimated 80 tokens per skill
  memory:     { count, tokens, files[] },  // CLAUDE.md + @-imports, recursed to depth 5
  total:      systemBase + mcpTools + skills + memory,
  modelContext: 1_000_000,                 // default 1M
}

Static, one-time computation at invocation. No session log required. Reads ~/.claude/settings.json, project .claude/settings.json, CLAUDE.md + @-imported files, enabled MCP configs.

Relationship to this issue

Not competing — two halves of the same question:

Approach	When	What it answers
Static budget (codeburn)	Before session starts	"How much context am I paying for just to boot?"
Dynamic hot-path (this issue)	After session completes	"How much did my actual sessions cost in CLAUDE.md cache-reads?"

Static number tells you the per-session tax floor. Dynamic number tells you the actual paid amount (which is static × session turns, approximately). Both useful. A user with a 10k-token static budget running 30-turn sessions pays 300k token-turns × cacheRead price just on setup — surfacing that as a single number up front motivates the CLAUDE.md trim.

Proposed additions to this issue's scope

Keep #10 as-is for the dynamic math (the primary feature). Add a sister command that surfaces the static budget:

burn context-budget [--project <path>]
# Output:
#
# Context budget for /Users/will/Projects/foo
#
#   System base:      10,400 tokens
#   Tool definitions:  5,200 tokens  (13 enabled)
#   MCP servers:       3,600 tokens  (9 tools across 2 servers)
#   Skills:              640 tokens  (8 skills available)
#   CLAUDE.md + imports: 3,127 tokens  (3 files)
#   ────────────────────────────────────────
#   Total static:     22,967 tokens
#
#   At your recent average of 34 turns/session × $0.50/M cache-read:
#     Per-session tax:  $0.39
#     Last 30 days:     $11.42 across 29 sessions

context-budget and claude-md advise (the dynamic output from this issue) become two sibling commands that answer the before and after questions.

Implementation

• Separate file: packages/analyze/src/context-budget.ts
• Reads project config surfaces: ~/.claude/settings.json, .claude/settings.json, ~/.claude/skills/*/SKILL.md (for count), CLAUDE.md + @imports recursion (same heading-based section parsing as this issue uses)
• Cross-references the ledger for "recent session turns" to produce the per-session-tax number

Priority

Add as a scope expansion to this issue. Not blocking the primary dynamic analysis; ships alongside or after. Roughly same effort as the CLAUDE.md parser already needed here.