* 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 <vazidmansuri005@users.noreply.github.com>
0efd6ed914