The Context Window as a Budget

Introduction

A context window is not storage — it is a budget. Every token you load into the window is spent, and the most expensive part of that budget is something operators rarely think about: the reread tax.

On every API call to Claude, the entire conversation history is reloaded from scratch. Every tool result, every previous response, every bash output. In a verbose 30-turn session, the accumulated history alone can be 50–60% of a 200K token window — and once you add the tool results and file reads still sitting in context, total consumption climbs well past 90% (the turn-by-turn timeline below). All of it is reloaded before Claude generates a single new word.

This is not a flaw — it is how transformer attention works. But it has massive engineering implications for how you structure CLAUDE.md, when you run compaction, and how you budget tool result sizes.

Where the Tokens Go

By turn 5, a typical well-engineered session has consumed roughly 18K tokens of the 200K window. The percentages below are shares of that ~18K consumed-so-far total — not shares of the full window — which is what makes the relative sizes visible:

• System prompt (CLAUDE.md + MCP instructions + skills): ~3,200 tokens, 18% of the ~18K consumed so far
• Tool results (file reads, search, bash): ~4,000 tokens, 22%
• Working memory (reasoning, scratch, intermediate outputs): ~2,900 tokens, 16%
• Conversation history: ~6,200 tokens, 34%
• Available for new output: the remaining ~182K of the window is still free at turn 5 — the point of the breakdown is the mix of what you have already spent, not how much is left

The critical insight: tool results and conversation history are the two largest and most variable categories. They are also the only two you can actively manage.

The Reread Tax in Practice

Watch what happens to a real session as turns accumulate:

At turn 1, you have nearly the full window available for output. The system prompt is static, history is empty, tool results are minimal.

By turn 15, you have read files, run tests, seen bash output, made several round trips with Claude. The history alone is probably 25,000–40,000 tokens. Add tool results that are still in the context and you are down to 40% availability.

By turn 30 with verbose tool output, you may have under 10% headroom. Claude is not degraded — it can still read everything — but hallucination risk increases when the model has less room to reason through long chains before hitting the output boundary.

At turn 50 with a verbose session, you can saturate a 200K window. This is not theoretical: Knox's sessions working on multi-file refactors with many test runs regularly hit this wall.

Engineering Responses to the Reread Tax

1. Compact early and often

The correct trigger for compaction is not "the session is broken" — it is "the session is past turn 15 with verbose tool output." Run a summary: what was built, what decisions were made, what remains. Start a new session with that summary as the initial context.

2. Control tool output verbosity

When reading files, read only the relevant sections. When running tests, capture only failures, not full pass output. When running bash commands that produce large outputs, pipe through grep or head. Every line of tool output is paid for again on every subsequent turn.

3. Keep system prompts lean

The system prompt loads on every single turn. A 400-line CLAUDE.md at 8,000 tokens costs 8,000 tokens on turn 1, turn 2, turn 3 — every turn. A 180-line CLAUDE.md at 3,600 tokens reclaims 4,400 tokens of permanent window headroom. The two are different costs: the 4,400 tokens is the standing space you get back in the window, while the billed input over 30 turns differs by ~132,000 tokens (4,400 × 30) — though prompt caching, which discounts a stable system-prompt prefix, softens that billing gap substantially.

4. Use the /compact command

Claude Code's /compact command triggers a built-in compaction that summarizes the session and resets the context with a condensed history. This is the mechanical tool for the engineering discipline described above.

Token Accounting: A Practical Exercise

Before your next complex session, estimate the token budget:

200,000 token window
- 3,600  CLAUDE.md system prompt (180 lines)
- 1,200  MCP instructions (memory-service, mcp-bridge, agent-gateway)
- 800    Skills context (2 loaded skills)
= 194,400 tokens remaining for work

Per-turn cost estimate:
- Average tool output: 800 tokens
- Average Claude response: 600 tokens
- Total per turn added to history: ~1,400 tokens

Turns until 60% used by history:
194,400 * 0.60 / 1,400 = ~83 turns

But if tool outputs are verbose (file reads, full test output):
Average tool output: 3,000 tokens
Total per turn: ~3,600 tokens
Turns until 60% used: 194,400 * 0.60 / 3,600 = ~32 turns

This arithmetic explains why verbose tool output is dangerous: it can shrink your effective session length from 80+ turns to under 35.

Real Implications for CLAUDE.md Design

The token budget analysis has a direct implication for CLAUDE.md length limits. The 200-line discipline is not arbitrary — it is token accounting. A 200-line CLAUDE.md is approximately 4,000 tokens. That is the budget cap for always-on context. Anything beyond that requires progressive disclosure (load on demand via agent-initiated reads or skill triggers — @imports resolve eagerly at load time, so they do not defer cost), not inline content.

This is why lessons.md lives in the project directory, not inlined into CLAUDE.md. It is why design-system/MASTER.md is read by the agent when UI work begins, not always loaded. It is why Semantic Memory Layer is queried at session start, not dumped into context wholesale.

Every deferred read is a choice to spend budget only when necessary. Every Tier 1 rule that survives in CLAUDE.md is a token investment that must earn its cost every session.

Summary

• The context window is a budget that depletes within sessions as history accumulates
• The reread tax: conversation history reloads completely on every API call — no compression
• By turn 30 with verbose tool output, you may have under 10% window headroom
• Compact before turn 20 with verbose sessions — not as a last resort but as a planned operation
• Control tool output verbosity: pipe through grep/head, read only relevant file sections
• The 200-line CLAUDE.md discipline is token accounting, not arbitrary rule-making

What's Next

The next lesson moves from the window itself to the architecture that fills it — the CLAUDE.md hierarchy, how four distinct levels of context inheritance work, and why the order they load matters.