---
name: context-budget-audit
description: "Audit and prune per-session context waste — MCP servers, plugins, skills, slash commands, subagents. Triggers: 'what's eating my context', 'trim my agent setup', 'what am I not using'. Do NOT use to harden a repo's agent config or hooks, for runtime trace/eval observability, or to size prompt text."
license: MIT
---

# Context Budget Audit

Everything loaded at session start — MCP tool schemas, skill descriptions, slash-command and subagent listings, enabled plugins — spends context before the user types a word. Measure that spend from local disk evidence and report what to prune, biggest wins first. Audit and recommendations run to completion; the one stop is editing the user's harness config.

## Workflow

1. **Run the engine.** `python3 scripts/audit_context_budget.py --repo-root <repo-root> --no-write` — use the current repo when it has a `skills/` directory, else the user's named repo. It scans active stores under `~/.claude`, `~/.codex`, `~/.agents`, and `~/.pi` for five kinds: `mcp`, `skill`, `command`, `subagent`, `plugin`. Never hand-roll the inventory or evidence scan. Add scope flags (`--only mcp`, `--evidence-days 0`, `--max-evidence-files N`, `--json`) only when the user asked or the default pass is too slow.
2. **Interpret** the output with `references/audit-framework.md`: evidence strength, idle-MCP detection, duplicates, estimate caveats.
3. **Recommend** with `references/recommendation-rubric.md`. Build the full prune plan: reclaimable headline, context footprint by kind, per-kind reclaim groups sorted by cost, weak-evidence and duplicate rows, kept items, caveats — with the exact removal command or file path on every recommendation.
4. **Act, stopping at the config boundary.** Deliver the complete decision view. If the user named items to remove: skills go through copy-validate-remove (preserve into `skills/<name>/`, validate with `npx skills add . --list` plus the repo's own gate, then remove the store copy and verify it is gone); slash commands and subagents are single `.md` files — confirm the exact path, delete only that file. Edits to `~/.claude.json`, `~/.codex/config.toml`, or `settings.json` (MCP servers, plugins) are the one genuine blocker: report the exact command (`claude mcp remove <name>`; disable via `enabledPlugins`) and end — never apply them yourself.

## Invariants

- The engine is read-only; it never edits or deletes anything.
- An MCP server with no observed `mcp__<server>__*` tool calls is **idle**: cost unknown-but-likely-largest, never "~0 tokens". Surface idle servers first.
- Footprint vs reclaim: "descriptions compressed" warnings come from aggregate load (count × description length), not individual non-use — the levers are fewer loaded items and shorter heavy descriptions, not only deleting unused ones.
- Token figures are estimates; counts are evidence matches; "no evidence" means none in the scan window, not never used. Generic names (`run`, `review`) are weak evidence.
- Never quote raw transcript, prompt, or credential content — display paths, counts, timestamps, and classification reasons only.
- System skills (`.system`) and plugin/marketplace caches are inventory-only, never prune targets. Disabled plugins cost zero context — not reclaim candidates.
- Never remove a skill store copy without a validated repo copy; if copies differ, remove nothing and flag the difference in the report.