context-audit

name

context-audit

description

Use when the user wants to cut Claude Code token cost or asks "why is this session so expensive / what's eating my tokens / trim my CLAUDE.md / reduce context". Audits the always-on context a project re-sends every turn (CLAUDE.md, memory, MCP servers, skills, agents), ranks it by per-turn token cost, and proposes concrete trims — including a leaner CLAUDE.md rewrite. Pairs with the Gander dashboard's per-session cache-hit / context-fill gauges.

Context Audit

Find what a project pays for on every single turn and cut it. The expensive thing in a long Claude Code session is rarely the user's prompt — it's the always-on context (system prompt + CLAUDE.md + loaded tools/skills + conversation) that gets re-sent each turn and billed as cache-read. Shave 5k tokens off something that loads every turn and you save it across the whole session.

The model (read first)

• Output costs ~5× input — but it's usually a small share of a long session's spend.
• Cache-read is cheap per token (~1/10th input) but you pay it on the whole context, every turn — so a 50-turn session re-reads its context ~50×. That multiplier is where the money goes.
• Therefore: the highest-leverage cut is anything fixed and re-sent every turn. In order of typical size: the conversation itself (→ /compact), CLAUDE.md files, enabled MCP servers (their tool schemas), available skills (name + description listed each turn), memory, agents, hooks.

Step 1 — Get the live signal (if Gander is running)

Ground the audit in real spend before guessing. The bridge runs on http://localhost:3131:

curl -s http://localhost:3131/api/usage

In bySession, find this project's sessions and read: cacheHit, outShare, ctxPct, costUSD.

• High cacheHit (>90%) + low outShare (<15%) → the lever is context size, not verbosity. Focus on CLAUDE.md / MCP / /compact.
• High outShare (>25%) → answers are verbose; a terse-output style helps more than trimming context.
• High ctxPct (>70%) → recommend /compact now (also surfaced as a button in the Gander agent modal).

If the bridge isn't up, skip to Step 2 — the file audit stands on its own.

Step 2 — Inventory the always-on context

Measure each item's size. Rough token estimate: tokens ≈ characters ÷ 4 (use ÷3.5 for dense code/markdown). Count chars:

# bash / macOS / Linux
wc -c CLAUDE.md ~/.claude/CLAUDE.md 2>/dev/null
find . -name CLAUDE.md -not -path '*/node_modules/*' -exec wc -c {} +

# Windows PowerShell
(Get-Content .\CLAUDE.md -Raw -ErrorAction SilentlyContinue).Length
(Get-Content $env:USERPROFILE\.claude\CLAUDE.md -Raw -ErrorAction SilentlyContinue).Length

Inventory, each as ~tokens/turn:

1. CLAUDE.md — global (~/.claude/CLAUDE.md) + project + any nested ones in the working tree. All in-scope ones load every turn.
2. MCP servers — list enabled ones (.mcp.json in the project, enabledMcpjsonServers / enableAllProjectMcpServers in .claude/settings.json, and ~/.claude.json). Each enabled server injects all its tool schemas into every turn — often the biggest hidden cost. Note which ones the session actually used (check the transcript / Gander activity); unused = pure waste.
3. Skills — every available skill's name + description is listed each turn (progressive disclosure). Count them and total the description lengths (~/.claude/skills/*/SKILL.md + project .claude/skills). Long descriptions on rarely-used skills add up.
4. Memory — ~/.claude/CLAUDE.md memory blocks / MEMORY.md + any auto-loaded memory files.
5. Agents & hooks — agent front matter and hook output that lands in context.

Step 3 — Rank and decide

Sort the inventory by tokens/turn, largest first. For each, ask one question: is this needed on every turn?

• Needed every turn → compress it (Step 4), don't remove.
• Needed sometimes → move the detail into an on-demand skill or a file the agent Reads when relevant, leaving a one-line pointer in CLAUDE.md. (This is the core move: progressive disclosure beats always-on.)
• Not needed here → disable it for this project (esp. MCP servers — use disabledMcpjsonServers, or the Gander Config panel).

Quantify: tokens_saved/turn × typical_turns × cache-read_price (Opus cache-read ≈ $1.50/M, Sonnet ≈ $0.30/M). Show the per-session dollar estimate so the trim is justified.

Step 4 — Deliverables

Produce, concretely:

1. A ranked table — item · ~tokens/turn · used? · verdict (keep / compress / defer / disable).
2. A leaner CLAUDE.md rewrite — same meaning, fewer tokens. Cut: restated defaults, narrative prose, duplicated history, anything the code/README already says. Keep: non-obvious constraints, commands, conventions. Show the before/after char (≈token) count.
3. An MCP/skill trim list — exactly which servers to disable for this project and which skill descriptions to tighten, with the per-turn savings each.

Step 5 — Re-measure (and the cache caveat)

• Editing CLAUDE.md mid-session busts the prompt cache (forces a full cache-write at ~1.25× input that turn). So savings show up on the next session, not the one you're in — don't be alarmed by a one-turn cost bump.
• After the next session runs, re-check cacheHit / ctxPct / costUSD in /api/usage (or the Gander modal) to confirm the drop.

Safety

• Read-only by default. Audit and propose; let the user apply CLAUDE.md edits and MCP changes. Never delete a memory or disable a server without showing what it is and confirming.
• Don't over-trim: cutting a real constraint makes Claude guess wrong, then you pay for the redo. Compress wording, preserve meaning.