context-budget

name	context-budget
description	Audit context window consumption across LOTRAOM agents, skills, rules, MCP servers, and CLAUDE.md. Report token estimates, flag bloat, recommend trims.
argument-hint	[{"optional":"--verbose for per-file breakdown"}]

Context Budget

Quantifies what LOTRAOM's .claude/ setup consumes from the context window before a single user message is processed. Drives every other context optimization decision.

Adapted from affaan-m/everything-claude-code via TAOM 2026-05-17.

When to Use

• Baseline diagnostic before optimizing the harness
• Session feels sluggish or hits compaction earlier than expected
• After adding agents, skills, rules, hooks, or MCP servers
• Planning to add more components and want to know if there's room

How It Works

Phase 1: Run the scan

bash .claude/skills/context-budget/scan.sh

This walks every .claude/ component, the .mcp.json, and CLAUDE.md, then prints a structured report.

For a per-file breakdown, run with --verbose:

bash .claude/skills/context-budget/scan.sh --verbose

Phase 2: Read the report

Sample structure:

LOTRAOM Context Budget Report
=============================

Total estimated baseline overhead: ~XX,XXX tokens
Context model: Claude Opus 4.7 (1M)
Effective available context: ~XXX,XXX tokens (XX% headroom)

Component Breakdown:
+-----------------+-------+-----------+
| Component       | Count | Tokens    |
+-----------------+-------+-----------+
| CLAUDE.md       | 1     | ~X,XXX    |
| Agents          | N     | ~X,XXX    |
| Skills          | N     | ~X,XXX    |
| Rules           | N     | ~X,XXX    |
| MCP servers     | N     | ~XX,XXX   |
| Hooks (shell)   | 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

Phase 3: Decide

Use the report to answer:

Question	Threshold	Action
Are skills loading bodies into base context?	Skills total >10K tokens	Verify load semantics; consider trimming
Are MCP servers dominating overhead?	MCP >50% of total	Audit for CLI-replaceable servers (gh, git wrappers)
Is CLAUDE.md too long?	>300 lines	Move repeating rules into scoped .claude/rules/*.md files
Are agent descriptions bloated?	>30 words in any agent	Tighten frontmatter — descriptions are loaded into every Task spawn
Are individual files heavy?	Skill >400 lines, Agent >200, Rule >100	Split or reference an external doc

Phase 4: Record baseline

After the first run on a clean session, record numbers in docs/context-budget-baseline.md. Re-run after any harness change to detect creep.

Token Estimation

The scanner uses simple heuristics:

• Prose markdown (skills, agents, rules, CLAUDE.md): words × 1.3
• Code-heavy files (.sh hooks, JSON): chars / 4
• MCP tools: ~500 tokens per declared tool, fixed estimate
• MCP server overhead: ~200 tokens per server (config + metadata)

These match Anthropic's published rough tokenizer behavior to within ~10%. Good enough for budget decisions; not exact.

What's Counted

Path	What it represents
CLAUDE.md	Always loaded into every session
.claude/agents/*.md	Agent descriptions loaded with every Task tool spawn (full body loaded only when invoked)
.claude/skills/*/SKILL.md	Skill frontmatter eager; body only when invoked
.claude/rules/*.md	Scoped rules; loaded conditionally based on file glob, counted as worst-case
.claude/hooks/*.sh	Hook scripts — not loaded into context, but counted to surface candidates for consolidation
.claude/memory/MEMORY.md	Project-local memory (first ~200 lines / ~25KB whichever binds first)
.mcp.json	MCP server count + estimated tool count overhead

What's NOT Counted

• User message history (variable)
• System prompt boilerplate from Claude Code itself (fixed, ~3-5K tokens)
• Plan files
• Tool call results during a session

Best Practices

• MCP is usually the biggest lever. Each tool schema costs ~500 tokens. A 30-tool server eats more than every skill combined.
• Agent descriptions are loaded always. Even if the agent is never invoked, its description sits in the Task tool context for every spawn decision.
• Verbose mode is for debugging. Don't run it for routine audits — it drowns the signal.
• Audit after changes. Run after adding any agent/skill/MCP server to catch creep early.

Expected LOTRAOM Inventory (post-TAOM-port, 2026-05-17)

• 8 existing agents + ~1 new (taleworlds-researcher) = 9 agents
• ~12 existing skills + 4 priority TAOM-ported = ~16 skills
• 15 scoped rules
• ~6 existing hooks + 9 priority TAOM-ported = ~15 hooks
• 5 MCP servers via .mcp.json

If MCP dominates and CLAUDE.md is large, the highest-leverage trim is usually MCP server pruning, not skill refactoring.