mxrsv Context Budget
The Rule
KNOW YOUR TOKEN COSTS. EVERY COMPONENT HAS A PRICE.
Agent descriptions load every time. MCP tools cost ~500 tokens each. Skills load on invocation. Bloat accumulates silently.
When to Use
- System feels slow, noisy, harder to steer, or hitting context limits
- Before adding new agents/skills/MCP servers
- Periodic maintenance (monthly)
- After major system changes
Process
Phase 1: Inventory
Scan and estimate token cost for each component. Audit the harness you are running in — the columns differ, the method does not:
| Component | How to estimate | Claude Code | Codex |
|---|---|---|---|
| Agents | words × 1.3 |
.claude/agents/*.md (project) + ~/.claude/agents/*.md (user) |
~/.codex/agents/*.toml |
| Skills | words × 1.3 (SKILL.md only — extra files load on demand) |
~/.claude/skills/*/SKILL.md |
~/.codex/skills/*/SKILL.md + ~/.agents/skills/*/SKILL.md |
| Instructions | words × 1.3 |
all CLAUDE.md files |
all AGENTS.md files |
| Rules | words × 1.3 |
~/.claude/rules/*.md |
already folded into ~/.codex/AGENTS.md |
| MCP servers | ~500 tokens per tool |
/mcp or settings.json |
[mcp_servers.*] in ~/.codex/config.toml |
| Hooks / config | read once, always on | settings.json hooks |
~/.codex/hooks.json, config.toml |
# Quick word count for all agents
wc -w ~/.claude/agents/*.md # Claude Code
wc -w ~/.codex/agents/*.toml # Codex
# Quick word count for all skills (both roots — Codex reads ~/.agents/skills natively)
find ~/.claude/skills ~/.agents/skills -name "SKILL.md" -exec wc -w {} +
# Count MCP tools loaded
# Claude Code: /context · Codex: /status
Phase 2: Classify
| Category | Criteria | Action |
|---|---|---|
| Always needed | Used every session | Keep |
| Sometimes needed | Used weekly | Consider on-demand |
| Rarely needed | Used monthly or less | Remove or lazy-load |
Phase 3: Detect Issues
Flag these patterns:
| Issue | Threshold | Fix |
|---|---|---|
| Bloated agent description | >30 words in frontmatter description |
Shorten — description is for routing, not docs |
| Heavy agent | >200 lines | Move details to skill or reference doc |
| Heavy skill | >150 lines | Condense or split into SKILL.md + reference files |
| MCP over-subscription | >10 servers loaded | Disable unused servers |
| Instructions bloat | CLAUDE.md / AGENTS.md >200 lines |
Split into focused rules files |
| Redundant components | Agent + skill overlap | Merge or clarify boundaries |
| Duplicate skill roots | Same skill name in two roots (e.g. ~/.codex/skills and ~/.agents/skills) |
Keep one source, symlink the other — see ~/.claude/scripts/sync-agents-skills.sh |
| Unused components | Never referenced in flows | Remove |
Phase 4: Report
[CONTEXT BUDGET AUDIT]
Total estimated overhead: {n} tokens
| Component | Count | Tokens | % |
|--------------|-------|--------|---|
| Agents | {n} | {n} | % |
| Skills | {n} | {n} | % |
| Instructions | {n} | {n} | % |
| MCP tools | {n} | {n} | % |
| Rules | {n} | {n} | % |
Issues found: {n}
1. {issue} — {component} — Save: ~{n} tokens
2. {issue} — {component} — Save: ~{n} tokens
Top 3 recommendations:
1. {action} — saves ~{n} tokens
2. {action} — saves ~{n} tokens
3. {action} — saves ~{n} tokens
Capacity: {remaining}% free after overhead
Key Insights
- MCP is the biggest lever — each tool schema ~500 tokens. 10 servers × 5 tools = 25,000 tokens
- Agent descriptions load always — even if agent never runs. Keep short.
- Skill SKILL.md loads on invocation — extra files in skill folder load only when read
- Instructions load always —
CLAUDE.md/AGENTS.md: every token counts
Enforcement
- ALWAYS include token estimates with evidence
- ALWAYS produce actionable, file-based recommendations
- PREFER deletion over rewriting when a component adds no clear value
- NEVER recommend removing components without checking if they're referenced