Context size and limits
How large context windows are in practice, what eats tokens fastest, and how Claude Code surfaces usage.
Models are advertised with large context limits (for example hundreds of thousands of tokens). That number is an upper bound, not a guarantee of perfect recall across every byte. In real sessions, latency, cost, and attention still push you toward smaller effective context than the brochure suggests.
Orders of magnitude
Think in rough tiers (exact figures change with model and product):
- Short: a few pages of code plus chat: comfortable; the model can hold most of it in focus.
- Medium: a module or small service, several files, plus conversation: workable if you structure prompts and avoid dumping binaries.
- Long: “the whole repo in one paste” or dozens of full file reads: often possible to fit but expensive and easy to dilute signal.
Tool output counts. A Read of a generated bundle or a huge JSON log can crowd out your instructions and recent decisions in one shot.
One-million-token windows: capacity without a free lunch
Claude 4.6 and later models include a ~1M token context window at standard API pricing. That removes an old excuse, “it will not fit”, but it does not remove cost or quality tradeoffs.
- Cost still scales with tokens. Long inputs mean more input tokens billed at the model’s list rate (and agent loops add many turns). See Claude pricing.
- No surcharge ≠ cheap. Flat per-token pricing means a 900K-token prompt is not discounted just because it is one request, it is simply 900K times the per-token price.
- Claude Code may bundle usage differently from the API; use
/usagein session.
The “fill the window” trap
A common failure mode after 1M windows ship:
@ ranges, a subagent summary, or a smaller model on a clean thread.Heuristic: if you cannot name why each large chunk must be in-context this turn, leave it out or summarize it. Often a curated small context beats a higher-tier model with a noisy megacontext for shipping a correct patch.
Example prompt
Do not maximize context. List the smallest set of files or line ranges you need for this bug; if you are unsure, read summaries first and only then pull full files. Goal: correct fix, minimal tokens.What Claude Code shows you
Use in-product tools to make the abstract concrete:
/context(when available in your build) visualizes how full the window is./usagehelps you see how large contexts add up across long agent loops.
Typing / and checking /help is the accurate list for your installed version.
Design habits that stay under budget
- Attach the smallest useful slice:
@path#line-rangeor a folder, not the whole tree unless needed. - Put stable truth in git:
AGENTS.md, plan files, specs, so you re-read a file instead of re-explaining history in chat. - Delegate heavy exploration to subagents so the main thread gets a summary, not every grep hit (see Subagents).
Example prompt
Before you read files: outline a minimal set of paths to inspect for this bug. Prefer ranges and summaries over full-file dumps. If you need one large file, quote only the functions that matter.