The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
feat(commands): add /context-budget optimizer command (#554)
vazidmansuri0050efd6ed9141e
diff --git a/commands/context-budget.md b/commands/context-budget.mdnew file mode 100644index 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.mdnew file mode 100644index 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