Step7

The documents ate the budget - tokens, a ledger and a compactor

25 September 2026 · 3 min read

claudetokensprocess

The in-game command interface over a river canyon at golden hour, with the build sidebar on the right.

A language model does not have memory. It has whatever you put in front of it, and you pay for every word of it, every time. This step is about the week we noticed that most of what our agents were reading was our own documentation.

The day we looked

On 22 September, the ledger says, the project used about 9.45 million tokens in one day. Nothing was wrong: a lot of work got done. But a ledger is only useful if you look at it, and when we did, two things stood out.

First, agents were reading whole files. A C++ source file is thousands of lines; the task usually involved forty of them. Second, the documents were getting very large, because the system works by writing everything down.

We keep, among others: a plan (every task, in the owner's own words), a progress log (one entry per finished row, with numbers and proof), a handoff queue between roles, and a decisions file. Each one is useful. Together, in two and a half days, they went from about one million characters to about 2.5 million: +148 per cent, or roughly 618,000 tokens of text. Most of it was two files.

File	22 Sep	25 Sep
Handoffs (characters)	78,631	373,789
Progress log	101,144	364,459
Design review	48,679	161,342
Enemy-AI notes	90,909	178,847

At about four characters per token, a role that opened the handoff file whole was reading about 93,000 tokens before it had done a thing.

The fix: a role whose job is to read less

We added a compactor (it is on the roster as a normal role, with its own file) and gave it four duties:

Keep a one-page brief, Docs/BRIEF.md, that every role reads first. It says where the project is, what is open, who has what, and which lines of which file are newer than the brief.
Keep a ledger, Docs/TOKENS.md, of file sizes and tokens per run.
Roll finished work out of the live documents into Docs/archive/, leaving a pointer behind. A script, scripts/compact_docs.py, moves the text byte for byte and never rewords it.
Give each role a reading budget: under 6,000 tokens before work starts.

On 25 September the owner approved a wider roll. The three big logs shrank from about 864,000 to 569,000 characters: 295,267 characters, roughly 73,800 tokens, gone from the live files. We checked it the boring way: every original line was found again, either in the live file or in the archive, and a second run moved nothing.

Three rules that came from the numbers

We wrote these into the rulebook that every agent reads:

Never read a whole source file. Search for the symbol, read about sixty lines around it.
Change an existing file with an edit, never a rewrite. A rewrite re-sends the whole file, and it can silently drop lines.
One deliverable per run. When an agent nears about 250,000 tokens, it stops, writes a short state, and a fresh agent takes over.

The last one felt wrong at first. It is cheaper to continue than to start again, surely? It is not: a long-lived agent carries every old tool result in its context. A fresh agent with a good three-line brief starts light.

A resumed agent is not a continuing worker. It is a very expensive reader.

Where the money still goes

Be honest about the limits. A ledger of tokens per run needs someone to quote the usage line from each run, and for several days nobody did. The ledger says so itself: "No run from 2026-09-23 to 2026-09-25 was logged here." The compactor's rules help, but they do not stop the logs growing about 110,000 characters a day each; they only keep the growth out of the context.

What we would do differently

Budget the reading on day one. A one-page brief and a rule about whole files would have cost an hour at the start.
Log the usage line of every run automatically. A hand-kept ledger has holes.
Archive on a schedule, not in a panic.

Try it yourself

Count the characters in the files your agent reads before it starts, divide by four, and decide whether that is what you want to pay for. Then give that number to a role as a budget.

Next: Where the trees, shrubs and scenery came from (27 September 2026)

Start at Step 1 All 27 steps