Context File Size and Token Budget: Measuring What You Can Afford

A 3,000-token context file is 1.5% of a large window. It is also competing for attention with every source file the agent needs to read, on every session, forever.

Context is a budget, not a container

The mental model most people carry is that the context window is a container you fill until it is full. A more accurate model is a budget you spend, where everything you buy competes with everything else for the model's attention.

Under the container model, a 200,000-token window means you can afford a 3,000-token context file without consequence — it is 1.5% of capacity. Under the budget model, that file is competing with the source files the agent needs to read, and the question is not whether it fits but whether it is worth more than what it displaces.

What is actually in the window

During a real session the window holds roughly this:

Only one row is under your direct control, and it is the smallest. That sounds like an argument that context file size does not matter much. It is actually the opposite: because your file is small and early, it has unusually good positional properties, and wasting that position on filler is expensive in a way the raw token count understates.

Position matters as much as size

Models attend unevenly across a long context. Material at the beginning and end tends to be weighted more heavily than material in the middle — a well-documented pattern, and one with a direct implication for how you structure a context file.

A thirty-line file is all beginning. A three-hundred-line file has a middle, and whatever sits in that middle is the least likely thing to influence behaviour. If your file has grown past a screen, the practical question is not "is this too long" but "which of my rules is now in the dead zone".

Measuring what your file costs

Token count is not word count. English averages roughly 1.3 tokens per word, but code, paths and punctuation run considerably higher — a line like `pytest tests/unit -x -q` is dense in tokens relative to its apparent size.

import tiktoken, pathlib, sys

enc = tiktoken.get_encoding("cl100k_base")
total = 0
for p in sorted(pathlib.Path(".").rglob("AGENTS.md")):
    n = len(enc.encode(p.read_text()))
    total += n
    print(f"{n:6d}  {p}")
print(f"{total:6d}  TOTAL (every session pays the root file)")

Run it. Most teams are surprised in one direction or the other, and either result is useful. A root file over about 1,200 tokens deserves a hard look; a root file under 300 is either admirably disciplined or missing something.

A budget worth adopting

These are not laws of nature; they are thresholds beyond which, in practice, files stop being read carefully and start being skimmed. Treat the ceiling as a trigger for review rather than a hard error — when you hit it, something in the file has stopped earning its place.

What to do when you are over budget

In descending order of how much they help:

1. Apply the discoverability test. Anything the agent could learn by reading the repo comes out. This alone usually recovers 40–60% in files that have never been pruned.
2. Push rules into nested files. A rule that applies to one package should not be on every session's bill.
3. Replace prose with a pointer. "Deployment is documented in docs/deploy.md; read it before changing infra/" is fifteen tokens instead of six hundred, and the agent follows the link when the task calls for it.
4. Convert rules into checks. A rule enforced by a linter can often be stated in a fraction of the words, because you no longer need to explain the edge cases — the tool handles them.
5. Delete rules that no longer apply. Files accumulate warnings about problems that were fixed a year ago. Nobody removes them because removal feels risky and there is no forcing function.

Where the rest of the budget goes

Your context file is the smallest controllable line item, but it is not the only one. Two others are worth attention because they dwarf it.

Tool definitions

Every tool available to the agent carries a schema in the context — name, description, parameters. A handful of tools is a few hundred tokens. Thirty MCP servers, each exposing a dozen tools, is several thousand, present on every single request before the agent has read a line of your code.

This is the most commonly overlooked cost in an agent setup. Installing an MCP server feels free because nothing visibly changes. It is not free; you have added its entire tool surface to the standing overhead of every session. Audit what is connected and disconnect what you are not using — there is a security argument for the same habit, which is a separate discussion.

Files the agent opens

By far the largest line item, and mostly emergent. You influence it indirectly: a well-organised repository where related code sits together needs fewer files open to establish context than one where a single feature is spread across six directories.

This is worth stating plainly because it reframes an old argument. Codebase organisation has always been justified on human comprehension grounds. It now has a second, more measurable justification — a coherent module boundary means an agent reads three files instead of eleven, on every task, forever.

The compounding argument

One reason to care that is easy to miss: this cost is paid on every session, by every engineer, forever. A 2,000-token root file across a team of ten running six sessions a day is 120,000 tokens a day of overhead — and that is the small part. The real cost is the attention those tokens divert from the code, on every single task, in a way nobody will ever measure or attribute.

Trimming eight hundred tokens from a context file is unglamorous work with no visible result. It is also one of the few changes that improves every future session in the repository at once.