Token Audit

/token-audit — Context Token Audit

Purpose: Measure how many tokens your Claude Code configuration consumes before any user task begins. Identify the biggest sources of overhead. Produce a concrete action plan with savings estimates.

What You Will Measure

Key insight: .claude/rules/ loads every .md file at session start. Commands and agents are lazy-loaded — zero cost until invoked.

Step 1 — Run the Measurement

echo "=== PROJECT CLAUDE.md ===" && wc -c CLAUDE.md 2>/dev/null || echo "none"

echo ""
echo "=== RULES FILES (sorted by size) ===" && find .claude/rules -name "*.md" 2>/dev/null \
  | xargs wc -c 2>/dev/null | sort -rn | head -20

Then calculate the full budget:

PROJECT=$(wc -c < CLAUDE.md 2>/dev/null || echo 0)
RULES=$(find .claude/rules -name "*.md" 2>/dev/null | xargs cat 2>/dev/null | wc -c || echo 0)
TOTAL=$(( PROJECT + RULES + 30000 ))

echo "Project CLAUDE.md  : ~$(( PROJECT / 4 )) tokens"
echo "Rules (auto-loaded): ~$(( RULES / 4 )) tokens"
echo "System prompt      : ~7,500 tokens"
echo "---"
echo "TOTAL fixed context: ~$(( TOTAL / 4 )) tokens"
echo "% of 200K window   : $(( TOTAL / 4 * 100 / 200000 ))%"

Step 2 — Classify Rules Files

For each file in .claude/rules/, output:

| File | Size (chars) | Class | Reasoning (one sentence) |

Sort by size descending within each class. Calculate total chars saved by removing RARELY and NEVER files.

Step 3 — Audit Hook Overhead

Hooks on PreToolUse and PostToolUse fire on every tool call. Check what you have:

python3 - << 'EOF'
import json, os
for path in [os.path.expanduser("~/.claude/settings.json"), ".claude/settings.json"]:
    if not os.path.exists(path): continue
    print(f"\n--- {path} ---")
    data = json.load(open(path))
    for event, hooks in data.get("hooks", {}).items():
        for h in hooks:
            cmd = h.get("command", "?")
            matcher = h.get("matcher", "*")
            print(f"  [{event}] matcher={matcher} → {cmd[:80]}")
EOF

Red flags: hooks that cat files unconditionally, git status on every call, multi-line debug echo never removed.

Step 4 — Action Plan

Output Format

## Token Audit — ctxharness — [DATE]

### Budget Summary

| Component | Tokens | % of total |
|-----------|--------|------------|
| Project CLAUDE.md | X | Y% |
| Rules (auto-loaded) | X | Y% |
| System prompt | 7,500 | Y% |
| **TOTAL** | **X** | **100%** |

Context window used before any task: X% of 200K

### Rules Classification

| File | Chars | Class | Action |
|------|-------|-------|--------|

### Action Plan

| Action | Savings | Effort |
|--------|---------|--------|

**Total achievable without infrastructure**: -X tokens → N% reduction

Interpreting Results