Skip to content

Commit 0efd6ed

Browse files
feat(commands): add /context-budget optimizer command (anomalyco#554)
* 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 anomalyco#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 anomalyco#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 <[email protected]>
1 parent 72c013d commit 0efd6ed

2 files changed

Lines changed: 164 additions & 0 deletions

File tree

‎commands/context-budget.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
description: Analyze context window usage across agents, skills, MCP servers, and rules to find optimization opportunities. Helps reduce token overhead and avoid performance warnings.
3+
---
4+
5+
# Context Budget Optimizer
6+
7+
Analyze your Claude Code setup's context window consumption and produce actionable recommendations to reduce token overhead.
8+
9+
## Usage
10+
11+
```
12+
/context-budget [--verbose]
13+
```
14+
15+
- Default: summary with top recommendations
16+
- `--verbose`: full breakdown per component
17+
18+
$ARGUMENTS
19+
20+
## What to Do
21+
22+
Run the **context-budget** skill (`skills/context-budget/SKILL.md`) with the following inputs:
23+
24+
1. Pass `--verbose` flag if present in `$ARGUMENTS`
25+
2. Assume a 200K context window (Claude Sonnet default) unless the user specifies otherwise
26+
3. Follow the skill's four phases: Inventory → Classify → Detect Issues → Report
27+
4. Output the formatted Context Budget Report to the user
28+
29+
The skill handles all scanning logic, token estimation, issue detection, and report formatting.

‎skills/context-budget/SKILL.md‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
---
2+
name: context-budget
3+
description: Audits Claude Code context window consumption across agents, skills, MCP servers, and rules. Identifies bloat, redundant components, and produces prioritized token-savings recommendations.
4+
origin: ECC
5+
---
6+
7+
# Context Budget
8+
9+
Analyze token overhead across every loaded component in a Claude Code session and surface actionable optimizations to reclaim context space.
10+
11+
## When to Use
12+
13+
- Session performance feels sluggish or output quality is degrading
14+
- You've recently added many skills, agents, or MCP servers
15+
- You want to know how much context headroom you actually have
16+
- Planning to add more components and need to know if there's room
17+
- Running `/context-budget` command (this skill backs it)
18+
19+
## How It Works
20+
21+
### Phase 1: Inventory
22+
23+
Scan all component directories and estimate token consumption:
24+
25+
**Agents** (`agents/*.md`)
26+
- Count lines and tokens per file (words × 1.3)
27+
- Extract `description` frontmatter length
28+
- Flag: files >200 lines (heavy), description >30 words (bloated frontmatter)
29+
30+
**Skills** (`skills/*/SKILL.md`)
31+
- Count tokens per SKILL.md
32+
- Flag: files >400 lines
33+
- Check for duplicate copies in `.agents/skills/` — skip identical copies to avoid double-counting
34+
35+
**Rules** (`rules/**/*.md`)
36+
- Count tokens per file
37+
- Flag: files >100 lines
38+
- Detect content overlap between rule files in the same language module
39+
40+
**MCP Servers** (`.mcp.json` or active MCP config)
41+
- Count configured servers and total tool count
42+
- Estimate schema overhead at ~500 tokens per tool
43+
- Flag: servers with >20 tools, servers that wrap simple CLI commands (`gh`, `git`, `npm`, `supabase`, `vercel`)
44+
45+
**CLAUDE.md** (project + user-level)
46+
- Count tokens per file in the CLAUDE.md chain
47+
- Flag: combined total >300 lines
48+
49+
### Phase 2: Classify
50+
51+
Sort every component into a bucket:
52+
53+
| Bucket | Criteria | Action |
54+
|--------|----------|--------|
55+
| **Always needed** | Referenced in CLAUDE.md, backs an active command, or matches current project type | Keep |
56+
| **Sometimes needed** | Domain-specific (e.g. language patterns), not referenced in CLAUDE.md | Consider on-demand activation |
57+
| **Rarely needed** | No command reference, overlapping content, or no obvious project match | Remove or lazy-load |
58+
59+
### Phase 3: Detect Issues
60+
61+
Identify the following problem patterns:
62+
63+
- **Bloated agent descriptions** — description >30 words in frontmatter loads into every Task tool invocation
64+
- **Heavy agents** — files >200 lines inflate Task tool context on every spawn
65+
- **Redundant components** — skills that duplicate agent logic, rules that duplicate CLAUDE.md
66+
- **MCP over-subscription** — >10 servers, or servers wrapping CLI tools available for free
67+
- **CLAUDE.md bloat** — verbose explanations, outdated sections, instructions that should be rules
68+
69+
### Phase 4: Report
70+
71+
Produce the context budget report:
72+
73+
```
74+
Context Budget Report
75+
═══════════════════════════════════════
76+
77+
Total estimated overhead: ~XX,XXX tokens
78+
Context model: Claude Sonnet (200K window)
79+
Effective available context: ~XXX,XXX tokens (XX%)
80+
81+
Component Breakdown:
82+
┌─────────────────┬────────┬───────────┐
83+
│ Component │ Count │ Tokens │
84+
├─────────────────┼────────┼───────────┤
85+
│ Agents │ N │ ~X,XXX │
86+
│ Skills │ N │ ~X,XXX │
87+
│ Rules │ N │ ~X,XXX │
88+
│ MCP tools │ N │ ~XX,XXX │
89+
│ CLAUDE.md │ N │ ~X,XXX │
90+
└─────────────────┴────────┴───────────┘
91+
92+
⚠ Issues Found (N):
93+
[ranked by token savings]
94+
95+
Top 3 Optimizations:
96+
1. [action] → save ~X,XXX tokens
97+
2. [action] → save ~X,XXX tokens
98+
3. [action] → save ~X,XXX tokens
99+
100+
Potential savings: ~XX,XXX tokens (XX% of current overhead)
101+
```
102+
103+
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.
104+
105+
## Examples
106+
107+
**Basic audit**
108+
```
109+
User: /context-budget
110+
Skill: Scans setup → 16 agents (12,400 tokens), 28 skills (6,200), 87 MCP tools (43,500), 2 CLAUDE.md (1,200)
111+
Flags: 3 heavy agents, 14 MCP servers (3 CLI-replaceable)
112+
Top saving: remove 3 MCP servers → -27,500 tokens (47% overhead reduction)
113+
```
114+
115+
**Verbose mode**
116+
```
117+
User: /context-budget --verbose
118+
Skill: Full report + per-file breakdown showing planner.md (213 lines, 1,840 tokens),
119+
MCP tool list with per-tool sizes, duplicated rule lines side by side
120+
```
121+
122+
**Pre-expansion check**
123+
```
124+
User: I want to add 5 more MCP servers, do I have room?
125+
Skill: Current overhead 33% → adding 5 servers (~50 tools) would add ~25,000 tokens → pushes to 45% overhead
126+
Recommendation: remove 2 CLI-replaceable servers first to stay under 40%
127+
```
128+
129+
## Best Practices
130+
131+
- **Token estimation**: use `words × 1.3` for prose, `chars / 4` for code-heavy files
132+
- **MCP is the biggest lever**: each tool schema costs ~500 tokens; a 30-tool server costs more than all your skills combined
133+
- **Agent descriptions are loaded always**: even if the agent is never invoked, its description field is present in every Task tool context
134+
- **Verbose mode for debugging**: use when you need to pinpoint the exact files driving overhead, not for regular audits
135+
- **Audit after changes**: run after adding any agent, skill, or MCP server to catch creep early

0 commit comments

Comments
 (0)