Token Economy

---
name: token-economy
description: Rubric for keeping Claude Code sessions cheap without losing quality — model tiering, cache hygiene, Read discipline, MCP pruning, subagent isolation. Use when cost feels wrong, before setting a budget, or when onboarding a teammate.
---

# Token economy

Three things drive cost in Claude Code: **context size**, **cache hit rate**, and **model choice**. Most waste comes from one of these being misconfigured and left alone.

## Model tiering — match the model to the task

| Task shape | Right model |
|---|---|
| Format fix, rename, small refactor, comment tweak | **Haiku** — ~15× cheaper than Opus, fast enough to feel instant |
| Routine feature work, bug fix, test writing, reviewing a small diff | **Sonnet** — the default; 5× cheaper than Opus |
| Architectural decision, cross-file refactor, debugging a subtle bug, reviewing a large diff | **Opus** — use when you need the reasoning, not by default |

Claude Code's `/fast` or model selection lets you pick. Don't use Opus by reflex for a typo fix.

## Cache hygiene — the 80% lever nobody talks about

Anthropic caches your prompt prefix for 5 minutes. A stable prefix = the next turn reads from cache at ~10% of input cost. A prefix that changes each turn = full price every time.

**What busts cache:**
- Timestamps in CLAUDE.md, in skill content, or in hook output
- Session IDs / UUIDs interpolated into system prompt
- Rotating "quotes of the day", random greetings
- MCP servers that return time-varying schema metadata

**What preserves cache:**
- CLAUDE.md that doesn't change day-to-day
- Skill/rule content that's additive, not mutating
- Hook `additionalContext` that's deterministic for a given input
- Turning off MCP servers you don't need (every schema change invalidates cache)

**How to check:** `/holocron:cost` — the cache hit rate line. Below 50% is a signal; above 70% is healthy.

## Read discipline — the most common leak

Claude's `Read` tool pulls whole files by default. A 2000-line file is ~8k tokens. Do that 5 times in a session and you've spent ~40k tokens reading the same file repeatedly.

**Pattern:**
1. `Grep` to find the relevant range (cheap — returns only matching lines)
2. `Read` with `offset` + `limit` for the range you identified

Holocron's `read-budget.js` hook nudges this on files > 500 lines, but the discipline has to be yours.

## MCP pruning — one-time setup, ongoing savings

Every MCP server's tool schemas ship to the model on every turn. An unused MCP server costs you tokens forever.

Audit with `/holocron:mcp-audit`. Disable servers you don't actively use. Two or three MCP servers is usually plenty; ten is a tax.

## Subagent isolation — don't pollute the main context

Research / exploration / "find me all the callers" work bloats the main transcript with files and noise you won't need after. Run it in a subagent:

```
Use the Explore agent to find how `authenticateUser` is called across the repo.
```

The subagent's findings come back as a summary; its exploration stays in its own context. Main session stays lean.

## Transcript discipline

Claude Code auto-compacts near the context limit, but compaction is lossy — it summarizes, and summaries forget things. Better:

- `/holocron:handoff` at logical boundaries — write state to a file, start fresh on the next task
- For long-lived work: `/holocron:plan` → plan file → execute → handoff. The plan file acts as durable memory.

## Subtle things

- **Large tool outputs stay in the transcript.** A single 20k-token tool result inflates every subsequent turn's input cost until compaction.
- **`Write` of a large file re-reads context.** Edit prefers over Write for big files.
- **Don't paste log output.** Summarize, grep, or point to a file.
- **Emojis are multi-token.** Harmless unless you're generating content heavy in them.

## Anti-patterns

- Running Opus on every turn "to be safe"
- Full-file Reads on generated/vendored files (`dist/`, `node_modules/`, generated protobufs)
- Keeping MCP servers installed that you tested once and never used again
- Timestamp-injecting SessionStart hooks (looking at you, naive `console.log(new Date())` in a hook that emits `additionalContext`)

## How to know it's working

Run `/holocron:cost` weekly. Healthy numbers:

- Cache hit rate > 60% (70%+ if you're disciplined)
- Median session cost under your per-session budget
- Per-model split skews Sonnet-heavy, with Haiku for small things, Opus for reasoning

If those aren't true, `@cost-analyst` can tell you why.