From 0efd6ed9141e08aa040ad0e290e09979361aefc8 Mon Sep 17 00:00:00 2001 From: vazidmansuri005 <47394979+vazidmansuri005@users.noreply.github.com> Date: Fri, 20 Mar 2026 12:50:23 +0530 Subject: [PATCH] feat(commands): add /context-budget optimizer command (#554) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(commands): add /context-budget optimizer command Adds a command that audits context window token consumption across agents, skills, rules, MCP servers, and CLAUDE.md files. Detects bloated agent descriptions, redundant components, MCP over-subscription, and CLAUDE.md bloat. Produces a prioritized report with specific token savings per optimization. Directly relevant to #434 (agent descriptions too verbose, ~26k tokens causing performance warnings). * fix: address review feedback on context-budget command - Add $ARGUMENTS to enable --verbose flag passthrough - Fix MCP token estimate: 45 tools × ~500 tokens = ~22,500 (was ~2,200) - Fix heavy agents example: all 3 now exceed 200-line threshold - Fix description threshold: warning at >30 words, fail at >50 words - Add Step 4 instructions (was empty) - Fix audit cadence: "quarterly" → "regularly" + "monthly" consistently - Fix Output Format heading level under Step 4 - Replace "Antigravity" with generic "harness versions" - Recalculate total overhead to match corrected MCP numbers * fix: correct MCP tool count and savings percentage in sample output - Fix MCP tool count: table now shows 87 tools matching the issues section (was 45 in table vs 87 in issues) - Fix savings percentage: 5,100 / 66,400 = 7.7% (was 20.6%) - Recalculate total overhead and effective context to match * fix: correct sample output arithmetic - Fix total overhead: 66,400 → 66,100 to match component table sum (12,400 + 6,200 + 2,800 + 43,500 + 1,200 = 66,100) - Fix MCP savings: ~1,500 → ~27,500 tokens (55 tools × 500 tokens/tool) to match the per-tool formula defined in Step 1 - Reorder optimizations by savings (MCP removal is now #1) - Fix total savings and percentage (31,100 / 66,100 = 47.0%) * fix: distinguish always-on vs on-demand agent overhead Agent descriptions are always loaded into Task tool routing context, but the full agent body is only loaded when invoked. The audit now measures both: description-only tokens as always-on overhead and full-file tokens as worst-case overhead. This resolves the contradiction between Step 1 (counting full files) and Tip 1 (saying only descriptions are loaded per session). * fix: simplify agent accounting and resolve inconsistencies - Revert to single agent overhead metric (full file tokens) — simpler and matches what the report actually displays - Add back 200-line threshold for heavy agents in Step 1 - Fix heavy agents action to match issue type (split/trim, not description-only) - Remove .agents/skills/ scan path (doesn't exist in ECC repo) - Consolidate description threshold to single 30-word check * fix: add model assumption and verbose mode activation - Step 4: assume 200K context window by default (Claude has no way to introspect its model at runtime) - Step 4: add explicit instruction to check $ARGUMENTS for --verbose flag and include additional output when present * fix: handle .agents/skills/ duplicates in skill scan Skills scan now checks .agents/skills/ for Codex harness copies and skips identical duplicates to avoid double-counting overhead. * fix: add savings estimate to heavy agents action for consistency * feat(skills): add context-budget backing skill, slim command to delegator * fix: use structurally detectable classification criteria instead of session frequency --------- Co-authored-by: vazidmansuri005 --- commands/context-budget.md | 29 +++++++ skills/context-budget/SKILL.md | 135 +++++++++++++++++++++++++++++++++ 2 files changed, 164 insertions(+) create mode 100644 commands/context-budget.md create mode 100644 skills/context-budget/SKILL.md diff --git a/commands/context-budget.md b/commands/context-budget.md new file mode 100644 index 00000000..30ec234b --- /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 00000000..f33a96eb --- /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