diff --git a/commands/context-budget.md b/commands/context-budget.md new file mode 100644 index 000000000..30ec234b9 --- /dev/null +++ b/commands/context-budget.md @@ -0,0 +1,29 @@ +--- +description: Analyze context window usage across agents, skills, MCP servers, and rules to find optimization opportunities. Helps reduce token overhead and avoid performance warnings. +--- + +# Context Budget Optimizer + +Analyze your Claude Code setup's context window consumption and produce actionable recommendations to reduce token overhead. + +## Usage + +``` +/context-budget [--verbose] +``` + +- Default: summary with top recommendations +- `--verbose`: full breakdown per component + +$ARGUMENTS + +## What to Do + +Run the **context-budget** skill (`skills/context-budget/SKILL.md`) with the following inputs: + +1. Pass `--verbose` flag if present in `$ARGUMENTS` +2. Assume a 200K context window (Claude Sonnet default) unless the user specifies otherwise +3. Follow the skill's four phases: Inventory → Classify → Detect Issues → Report +4. Output the formatted Context Budget Report to the user + +The skill handles all scanning logic, token estimation, issue detection, and report formatting. diff --git a/skills/context-budget/SKILL.md b/skills/context-budget/SKILL.md new file mode 100644 index 000000000..f33a96eb9 --- /dev/null +++ b/skills/context-budget/SKILL.md @@ -0,0 +1,135 @@ +--- +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. +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 │ +└─────────────────┴────────┴───────────┘ + +⚠ 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