context-budget

name context-budget description Audits Claude Code context window consumption across agents, skills, MCP servers, and rules. Identifies bloat, redundant components, and produces prioritized token-savings recommendations. Use when the context window is filling up too fast and the agents, skills, MCP servers, or rules consuming it need to be identified. metadata {"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) How It Works Phase 1: Inventory Scan all component directories and estimate token consumption: 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 Estimate schema overhead at ~500 tokens per tool 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 Phase 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 Phase 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 Phase 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. Examples 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% Best Practices Token estimation : use words × 1.3 for prose, chars / 4 for code-heavy files MCP is the biggest lever : each tool schema costs ~500 tokens; a 30-tool server costs more than all your skills combined 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