context-budget

name	context-budget
description	Audits Claude Code context window consumption across agents, skills, MCP servers, rules, and CLAUDE.md files — identifies bloat and redundant components and produces prioritized token-savings recommendations. Use when a session feels sluggish or degraded, after adding skills/agents/MCP servers, before adding more components, or when the user runs /context-budget or asks how much context headroom remains. Do NOT use for API billing/spend questions or for shortening a single response — this audits loaded-component overhead, not output length or account cost.
origin	ECC

Context Budget

Analyze token overhead across every loaded component in a Claude Code session and surface actionable optimizations to reclaim context space.

When to Use

• Session performance feels sluggish or output quality is degrading
• You've recently added many skills, agents, or MCP servers
• You want to know how much context headroom you actually have
• Planning to add more components and need to know if there's room
• Running /context-budget command (this skill backs it)

When NOT to use: API token billing or per-call cost questions (that is account spend, not context overhead) · trimming one long response (that is output style) · auditing a repo you have not read — every number in the report must come from a measurement run this session, never from memory of a past audit.

Inputs

Required before starting — verify each root actually exists (ls -d), never assume:

• Component roots: project-level .agents/, .claude/, and .Codex/ trees, each scanned for agents/, skills/, and rules/ subdirectories
• MCP config: .mcp.json (project) and/or user-level MCP settings — only top-level mcpServers is read
• CLAUDE.md chain: project + user-level CLAUDE.md files
• Optional: a verbosity request from the user (--verbose)

Absent-input rule (fail closed, bug-230): a root that does not exist is reported as ABSENT in the report — never estimated, never silently skipped, never given an invented number. If no root exists at all, stop and report that there is nothing to audit; zero components found is a finding, not a pass.

Procedure

Step 1 — Inventory

Scan all component directories and estimate token consumption. Run the measurement command in Verification below — every number in the report traces to that run, not to recall.

Agents (agents/*.md)

• Count lines and tokens per file (words × 1.3)
• Extract description frontmatter length
• Flag: files >200 lines (heavy), description >30 words (bloated frontmatter)

Skills (skills/*/SKILL.md)

• Count tokens per SKILL.md
• Flag: files >400 lines
• Check for duplicate copies in .agents/skills/ — skip identical copies to avoid double-counting

Rules (rules/**/*.md)

• Count tokens per file
• Flag: files >100 lines
• Detect content overlap between rule files in the same language module

MCP Servers (.mcp.json or active MCP config)

• Count configured servers and total tool count
• Detect whether tool search/deferred loading is enabled before estimating resident overhead
• Use ~500 tokens per tool only as potential upfront schema overhead when deferral is disabled
• Flag: servers with >20 tools, servers that wrap simple CLI commands (gh, git, npm, supabase, vercel)

CLAUDE.md (project + user-level)

• Count tokens per file in the CLAUDE.md chain
• Flag: combined total >300 lines

Step 2 — Classify

Sort every component into a bucket:

Bucket	Criteria	Action
Always needed	Referenced in CLAUDE.md, backs an active command, or matches current project type	Keep
Sometimes needed	Domain-specific (e.g. language patterns), not referenced in CLAUDE.md	Consider on-demand activation
Rarely needed	No command reference, overlapping content, or no obvious project match	Remove or lazy-load

Step 3 — Detect Issues

Identify the following problem patterns:

• Bloated agent descriptions — description >30 words in frontmatter loads into every Task tool invocation
• Heavy agents — files >200 lines inflate Task tool context on every spawn
• Redundant components — skills that duplicate agent logic, rules that duplicate CLAUDE.md
• MCP over-subscription — >10 servers, or servers wrapping CLI tools available for free
• CLAUDE.md bloat — verbose explanations, outdated sections, instructions that should be rules

Step 4 — Report

Produce the context budget report:

Context Budget Report
═══════════════════════════════════════

Total estimated overhead: ~XX,XXX tokens
Context model: Claude Sonnet (200K window)
Effective available context: ~XXX,XXX tokens (XX%)

Component Breakdown:
┌─────────────────┬────────┬───────────┐
│ Component       │ Count  │ Tokens    │
├─────────────────┼────────┼───────────┤
│ Agents          │ N      │ ~X,XXX    │
│ Skills          │ N      │ ~X,XXX    │
│ Rules           │ N      │ ~X,XXX    │
│ MCP tools       │ N      │ ~XX,XXX   │
│ CLAUDE.md       │ N      │ ~X,XXX    │
└─────────────────┴────────┴───────────┘

WARNING: Issues Found (N):
[ranked by token savings]

Top 3 Optimizations:
1. [action] → save ~X,XXX tokens
2. [action] → save ~X,XXX tokens
3. [action] → save ~X,XXX tokens

Potential savings: ~XX,XXX tokens (XX% of current overhead)

In verbose mode, additionally output per-file token counts, line-by-line breakdown of the heaviest files, specific redundant lines between overlapping components, and MCP tool list with per-tool schema size estimates.

Tag every number in the report with its evidence scope: measured this session = [repro]; word-count estimate = [inferred] (the ×1.3 heuristic is an approximation, not a token count). Present estimates as estimates — never as measured readings.

Verification

1. The inventory numbers come from a run, not from memory. From the repo root:

   python3 - <<'EOF'
   import json
   from pathlib import Path
   
   total = 0
   for root in (Path(".agents"), Path(".claude"), Path(".Codex")):
       if not root.is_dir():
           print(f"{root}: ABSENT — report as absent, do not estimate")
           continue
       for component in ("agents", "skills", "rules"):
           component_root = root / component
           if not component_root.is_dir():
               print(f"{component_root}: ABSENT — report as absent, do not estimate")
               continue
           files = list(component_root.rglob("*.md"))
           est = int(sum(len(p.read_text(errors="ignore").split()) for p in files) * 1.3)
           total += est
           print(f"{component_root}: {len(files)} .md files, ~{est:,} estimated tokens")
   
   mcp = Path(".mcp.json")
   if mcp.is_file():
       servers = json.loads(mcp.read_text()).get("mcpServers", {})
       print(f".mcp.json: {len(servers)} servers configured")
   else:
       print(".mcp.json: ABSENT — report as absent, do not estimate")
   print(f"TOTAL (file overhead estimate): ~{total:,} tokens")
   EOF
   

   PASS: exits 0 and prints one line per root plus a TOTAL line; every root count/token figure in the report matches this output, and any root printed as appears as absent in the report.

Examples

Worked example (this repo, run 2026-07-29)

Step-1 command executed from /Users/theceo/DevSkyy/.claude/worktrees/glimmering-crafting-shannon — observed output:

.claude/agents: 19 .md files, ~22,629 estimated tokens
.claude/skills: 350 .md files, ~584,239 estimated tokens
.claude/rules: 5 .md files, ~2,108 estimated tokens
.mcp.json: 2 servers configured
TOTAL (file overhead estimate): ~608,976 tokens

Reading: .claude/skills dominates at ~96% of file overhead [repro] — but raw file size is potential load, not loaded load: skills load on invocation, while every agent description and MCP tool schema is resident in-session. So the actionable lever here is agent-description and MCP-schema trimming, not deleting skill files. That distinction is exactly what step 2 of Verification protects.

Illustrative dialogues (format only — numbers are placeholders, never reuse them)

Basic audit

User: /context-budget
Skill: Scans setup → 16 agents (12,400 tokens), 28 skills (6,200), 87 MCP tools (43,500), 2 CLAUDE.md (1,200)
       Flags: 3 heavy agents, 14 MCP servers (3 CLI-replaceable)
       Top saving: remove 3 MCP servers → -27,500 tokens (47% overhead reduction)

Verbose mode

User: /context-budget --verbose
Skill: Full report + per-file breakdown showing planner.md (213 lines, 1,840 tokens),
       MCP tool list with per-tool sizes, duplicated rule lines side by side

Pre-expansion check

User: I want to add 5 more MCP servers, do I have room?
Skill: Current overhead 33% → adding 5 servers (~50 tools) would add ~25,000 tokens → pushes to 45% overhead
       Recommendation: remove 2 CLI-replaceable servers first to stay under 40%

Failure modes

• Numbers from memory instead of measurement — quoting token counts from a past audit or from training-data intuition. Every figure must trace to a step-1 run this session; a stale count is a hallucination with a decimal point.
• Fail-open on an absent root (bug-230 pattern) — a missing .claude/agents/ silently contributing 0 reads as "no agent overhead" when the truth is "not measured". Absent = reported ABSENT, never zero.
• Estimate presented as measurement (bug-287 pattern — evidence scope must cover claim scope) — the ×1.3 heuristic is [inferred]; claiming "your MCP servers cost exactly N tokens" requires the session's real /context reading, not arithmetic on file sizes.
• Double-counting mirrored skills — identical copies under .agents/skills/ counted twice inflate the total and manufacture fake savings. De-duplicate by content before summing.
• Conflating potential load with resident load — a 500-line skill that never triggers costs ~0 in-session; a 40-word agent description costs its full weight in every Task invocation. Ranking by raw file size alone inverts the real priority (see Worked example).
• Recommending removal of a component that is actually load-bearing — a "rarely needed" classification from step 2 is [inferred] until grepped: a component referenced by CLAUDE.md, an active command, or another skill is not removable. Cite the grep before recommending deletion.
• A counting run that dies is not a count — if the step-1 script errors mid-scan, its partial TOTAL is an artifact, not a result. Fix and re-run; never report a partial as the audit.

Callability model

The report must treat all discovered roots as callable inventory, not implicit resident context. Do not report zero as success for a missing root; report ABSENT and keep commands explicit.

Best Practices

• Token estimation: use words × 1.3 for prose, chars / 4 for code-heavy files
• MCP is the biggest lever only without deferral: with tool search enabled, registered tools remain callable while full schemas load on demand
• Agent descriptions are loaded always: even if the agent is never invoked, its description field is present in every Task tool context
• Verbose mode for debugging: use when you need to pinpoint the exact files driving overhead, not for regular audits
• Audit after changes: run after adding any agent, skill, or MCP server to catch creep early