Context window math for coding agents: why 200k tokens is not 200k useful tokens

ShowNico3 replies

3
NicoMember#1

A model with a 200k context window is not a model that can use 200k tokens. The number on the card is the size of the envelope. The question is how much of the envelope you can fill with things that help, before the cost and the attention of the model are both worse off.

What is actually in the envelope

For a coding agent, every single request carries:

  • the system prompt and the tool definitions,
  • the project instructions (an AGENTS.md, a CLAUDE.md, a contributing guide),
  • the repository map, or the list of files the agent has decided to look at,
  • the contents of the files it has read, which grows as it works,
  • the results of the tools it called, which is where the growth really happens.

The last two are the problem. Every tool call adds its output to the conversation, and nothing removes it. An agent that has read twelve files carries twelve files' contents in every subsequent request.

The arithmetic

Take a repository with 400 files. The full text of all of them is often 300,000 tokens, well past the window. The same repository with lockfiles, build output, vendored dependencies and binary files removed is often 40,000. That is the difference between "does not fit" and "fits with room to work", and it is a difference of what you put in the envelope, not of a bigger model.

/tools/repo-to-prompt builds the second version: a file tree plus the contents, fenced and labelled, with the noise skipped. /tools/token-counter counts it with the tokenizer of the model family you will use, because a count from another family is a rough guide, and a rough guide is not good enough when you are deciding whether to paste.

The second cost

Context is not free in memory either. The KV cache grows with the context you allocate, not with the part you use, and it is the part that decides whether the model fits on the card at all. On a 24 GB card a 32B model at Q4_K_M with 32k of context is tight; the same model with 128k allocated is not running at all. /tools/llm-vram-calculator does the weights-plus-cache sum, and /learn/kv-cache explains why it works that way, and /learn/context-window is the background on the difference between the window and the useful part of it.

The thing that actually helps

Once the conversation is long, the fix is not a longer window. It is summarising: the agent writes down what it has established, and the transcript of the exploration is replaced by the summary, with the important file contents kept and the dead ends dropped.

That is what the compacting commands in the coding agents do, and it is the single most effective thing you can configure, because it changes the size of every subsequent request rather than one of them. The rule of thumb for the rest: put the stable part first so it can be cached, and keep the volatile part at the end.

3 replies

Lewis ChengMember#2

The compaction point is the one people miss. The instinct is to raise the window, because a longer window looks like more capability, but a 200k window full of dead ends is worse than an 8k window with a good summary in it, both in cost and in how well the model does the task.

The agents that ship a compact command are the ones that stay usable in a long session.

NicoAuthorMember#3

In reply to Lewis Cheng (#2)

Agreed, and it is also why the repository map matters twice: once to keep the initial context small, and once so the summary has a place to point at when it says "the routing lives in this file".

KaceyMember#4

Another number that belongs in this budget: the tool definitions.

A client carrying twenty tools sends twenty schemas in every request, and those schemas are part of the stable prefix. A client with five well-chosen tools and one with twenty do not behave the same, and the difference is paid on every turn rather than once. Counting the tool definitions alone against the whole request tells you which side of that line you are on.