context-budget

name	context-budget
description	Estimate per-turn token cost of `.claude/` and `CLAUDE.md` — always-loaded vs path-scoped vs invoked-only, top contributors, over-budget flags. Add `--api` for exact tokenizer counts.
argument-hint	[--api]
disable-model-invocation	true

Estimate the token cost of this project's .claude/ configuration and CLAUDE.md so the user can see exactly which files load every turn versus only when triggered.

Step 1: Discover loadable files

From the project root:

ls CLAUDE.md 2>/dev/null
find .claude/rules -name '*.md' -type f 2>/dev/null
find .claude/skills -name 'SKILL.md' -type f 2>/dev/null
find .claude/agents -name '*.md' -type f 2>/dev/null
[ -f .claude/CLAUDE.md ] && echo "WARN: .claude/CLAUDE.md exists. CLAUDE.md belongs at the project root."

Skip any file under .claude/agents/README.md, .claude/rules/README.md, etc. Those are folder descriptions, not loaded by Claude Code at runtime.

Step 2: Classify rules by frontmatter

For every .md file in .claude/rules/, read the YAML frontmatter (the block between the first two --- lines).

Frontmatter contains	Classification	Per-turn cost
paths: [...]	Path-scoped	Loaded only when working near matched files
No paths: (or no frontmatter)	Always-loaded	Every turn

Other categories:

• ./CLAUDE.md -> always-loaded (by definition).
• .claude/skills/<name>/SKILL.md -> invoked-only (zero per-turn cost; only loads when the user runs /skill-name or, if disable-model-invocation is unset, when Claude auto-triggers it).
• .claude/agents/<name>.md -> invoked-only and runs in isolated context (per-invocation cost in its own session, not per-turn cost in the main thread).

Step 3: Count tokens per file

Default mode (no API call): chars-based heuristic. Anthropic documents that English text averages roughly 4 characters per token. Compute:

chars=$(wc -c < "$FILE" | tr -d ' ')
tokens=$((chars / 4))

Note this in the report so the user knows the count is approximate (within roughly 10 to 15 percent of the exact count for typical config text).

--api mode: if $ARGUMENTS contains --api:

if [ -z "$ANTHROPIC_API_KEY" ]; then
  echo "ERROR: --api requested but ANTHROPIC_API_KEY is not set. Falling back to heuristic."
else
  CONTENT=$(jq -Rs . < "$FILE")
  tokens=$(curl -s https://api.anthropic.com/v1/messages/count_tokens \
    -H "x-api-key: $ANTHROPIC_API_KEY" \
    -H "anthropic-version: 2023-06-01" \
    -H "content-type: application/json" \
    -d "{\"model\":\"claude-sonnet-4-6\",\"messages\":[{\"role\":\"user\",\"content\":$CONTENT}]}" \
    | jq -r '.input_tokens')
fi

The endpoint returns Anthropic's exact tokenizer count. That is the factual number Claude Code itself would see when loading the file.

Step 4: Aggregate and report

Sum tokens within each category, identify the top 3 contributors among always-loaded files, then print:

Context budget for <project root>
Method: heuristic (chars/4)        [or: Anthropic count_tokens API]

Always-loaded (every turn):                 ~N tokens
  CLAUDE.md                                  ~N tokens
  .claude/rules/code-quality.md  (always)      ~N tokens
  .claude/rules/testing.md       (always)      ~N tokens

Path-scoped (loaded near matched files):    ~N tokens (max, if every glob matches)
  .claude/rules/security.md      (paths: src/api/**, ...)  ~N tokens
  .claude/rules/frontend.md      (paths: **/*.tsx, ...)    ~N tokens

Invoked-only (zero per-turn cost):
  Cumulative size if every skill and agent loaded once: ~N tokens
  .claude/skills/<name>/SKILL.md   ~N tokens
  .claude/agents/<name>.md         ~N tokens

Top 3 always-loaded contributors:
  1. <file>   ~N tokens
  2. <file>   ~N tokens
  3. <file>   ~N tokens

Verdict: PASS / NEAR LIMIT / OVER BUDGET

End the report with the highest-leverage trim recommendation if any class is over budget.

Budget guidance (used to compute the verdict)

Class	Target	Hard cap	Action when over
CLAUDE.md	<25 non-blank lines	<50 non-blank lines	Trim per Phase 4 of /setupdotclaude.
Each always-loaded rule	<30 lines, ~250 tok	n/a	Push content to a path-scoped rule or into an agent.
Total always-loaded	<1000 tokens	<1500 tokens	Identify the single biggest contributor and trim it.

Caveats to mention in the report

• The heuristic is approximate. Re-run with --api (requires $ANTHROPIC_API_KEY) for the exact count from Anthropic's tokenizer.
• Claude Code does not expose live context window state to skills, so this report estimates "what would load each turn for this configuration", not "what's currently in your session window".
• Agents run in isolated context. Their prompt cost is per-invocation in their own session, not per-turn in your main thread.
• Skills cost zero until invoked. Most have disable-model-invocation: true, meaning they only fire on /name.
• Path-scoped rules cost zero unless the conversation touches files matching their globs.
• Hooks contribute to context only if they print to stdout. dotclaude's hooks are silent on success by design.