Context Budget

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)

Persisted-record bytes (optional)

For a local file diagnostic, explicitly select a stable, regular JSONL file or a snapshot you intend to inspect. Replace the example path below; this does not find or reconnect a session. The snippet prints aggregate byte counts only. It reads one line at a time, so memory use depends on the largest record; avoid very large records and actively growing files.

python3 - "/path/to/selected-session.jsonl" <<'EOF'import jsonimport sys
total = attachment = other = unclassified = 0try:    with open(sys.argv[1], "rb") as source:        for raw in source:            size = len(raw)            total += size            try:                record = json.loads(raw.decode("utf-8"))            except (UnicodeDecodeError, json.JSONDecodeError):                unclassified += size                continue            record_type = record.get("type") if isinstance(record, dict) else None            if not isinstance(record_type, str):                unclassified += size            elif record_type == "attachment":                attachment += size            else:                other += sizeexcept OSError:    print("Cannot read selected JSONL file.", file=sys.stderr)    raise SystemExit(1)
pct = attachment * 100.0 / total if total else 0.0print(f"persisted {total}B | attachment records {attachment}B ({pct:.1f}%) | "      f"other records {other}B | unclassified {unclassified}B")EOF

The three categories add up to the original file bytes, including line endings and blank lines. attachment is an exact record-type filter, not a guarantee about a harness's current internal schema. Other records have a different string type; malformed JSON, invalid UTF-8, nonobject values, missing or non-string types, and blank lines are unclassified. Neither category means "conversation," and the percentage is only a share of persisted bytes.

These counts do not establish active context, remaining room, token usage, billing, or what a reconnect loads. For current harness-reported context and usage, use the version-appropriate /context and /usage commands (/cost is an alias).

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:

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 tokensContext 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    │└─────────────────┴────────┴───────────┘
WARNING: Issues Found (N):[ranked by token savings]
Top 3 Optimizations:1. [action] → save ~X,XXX tokens2. [action] → save ~X,XXX tokens3. [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-budgetSkill: 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 --verboseSkill: 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