meltaA coding agent that reads a 300 KB source file whole puts roughly 80K tokens into its context, and then pays to carry them on every request until the session ends. Reading the 20 or 60 lines it needs costs a few hundred to a couple of thousand tokens. The fix has two halves: chunk down (search first, read by line range) and chunk up (stop growing files that big). Our own worst case is Chief, Melta's task runner, which lives in one file of 323,322 bytes and 5,833 lines.
Key facts
- Claude Code's Read tool takes
offsetandlimit. By default one call returns at most 25,000 tokens and refuses a whole file over 256 KB. - Grep with line numbers first, then read only the range around the hit.
- A read stays in context: every later request reads it again, from cache if you are lucky.
- Planned for Chief: a symbol map so the brief says "read lines 788 to 810", and a 300-line rule.
- Chunking up: keep a file to one concern and under about 300 lines.
Why does one big read cost so much?
An agent session is a growing conversation. Every request sends the whole context so far: the system prompt, the tools, your brief and every tool result, including every file read. Prompt caching makes a repeated prefix cheaper, but cheaper is not free. A rough sum, using a common rule of thumb of about 4 bytes per token for code (an estimate, not a count):
323,322 bytes / 4 ~ 80K tokens in context written to cache once at 1.25x ~ 100K input-token equivalents read from cache at 0.1x, 20 requests ~ 160K more a 23-line range ~ 300 tokens, carried the same way
That is one read. Agents often read the same big file again after an edit, or read a second big file to compare. On a long task the file you opened in the first minute can be the largest single cost of the session. It also pushes the session toward its context limit sooner, which brings a compact or a handoff, and each of those costs again.
What does chunking down look like?
Search, then read the range. In Claude Code the Grep tool returns matching lines with file and line number when you ask for content, and Read accepts offset and limit. The same pair in a shell:
$ grep -n "^export function costEstimate" chief/melta-chief.mjs
788:export function costEstimate(s, { taskTokens = 0, limits } = {}) {
$ sed -n 780,810p chief/melta-chief.mjs
Thirty-one lines instead of 5,833. The agent sees the function, its comment and its neighbours, and nothing else.
Claude Code already pushes in this direction for very big files. Its docs say a whole-file read over 256 KB is refused with an error that tells Claude to read a portion with offset and limit or search with Grep, and a file over the token limit returns only its first page with a notice saying how to read more. Our file is past 256 KB, so a worker cannot read it whole by default; it pages. Paging through all of it is the same leak in four pieces.
A few habits help an agent stay in ranges:
- Grep for the symbol, not the topic. A function or constant name lands on one line; a word like "cost" lands on two hundred.
- Read a window, not a line. Twenty to sixty lines around the hit is usually enough to see the shape of the code.
- Read once. If a task needs more than two ranges of one file, it is cheaper to read the file once and say so, than to nibble at it ten times.
- Do not re-read after your own edit. An edit tool that fails tells you so; the file is what you wrote.
How can the brief name ranges instead of files?
A worker that is told "the change is in chief/melta-chief.mjs" still has to find where. A worker told "read chief/melta-chief.mjs 788 to 810, costEstimate" starts at the right line. The planner can only write that if something has already mapped symbols to line ranges.
Chief has a map today, specs/map.md, written by melta-chief map. It is a folder map: one line per top-level folder with what it is, its test command, the workflow that ships it and its most-changed files. It does not hold line ranges. The planned next step is a symbol map per repo on the computer (symbol or heading to file, start and end line), refreshed by the same command, so the brief can name ranges. That is planned, not shipped.
What does Chief measure today, and what is planned?
| Signal | Status | What it shows |
|---|---|---|
| Reads and searches before the first edit | Measured per task | How long the worker looked around |
| Files read twice | Measured per task | Re-reads, often of the same big file |
| Files read outside the brief | Measured per task | What the brief should have named |
| Lines and bytes per read | Planned | Whole-file reads of files over 300 lines |
| Bytes read but never edited | Planned | Reading that did not lead anywhere |
The planned rule for briefs follows from the same numbers: a file over 300 lines is read by range only, and a worker that needs more than two ranges of one file reads it once and says so in its receipt. Until the read-size metric exists, we cannot say how much this saves, so we do not.
What does chunking up mean?
Chunking down is a workaround. The real fix is not writing a 5,833-line file. Chief grew one feature at a time, each a reasonable addition, until records, routing, briefs, review and its MCP server all shared one file. Every task that touches any of them now starts inside the same 323 KB. The brief for this post's research said 250 KB; it was 323 KB by the time we measured. Big files grow.
The plan is to split it by concern into modules: records, routing, packs, review and mcp, and to keep files Chief writes under about 300 lines per concern. Three hundred is not magic. It is small enough that a whole read costs little, and large enough that a module is not split into fragments you must read together anyway. A file that is one concern also gives grep a cleaner answer: the hit is in the file you meant.
Common questions
Can Claude Code read a file larger than 256 KB?
Yes, in pages with offset and limit. The docs say that from v2.1.296 it can also read the whole file in one call with allow_large: true when it needs to, sized against the room left in the context window.
How many tokens is a file?
It depends on the language and the tokenizer. Four bytes per token is a rough rule for code; measure with your agent's usage numbers if it matters.
Does prompt caching make big reads free?
No. A cache read is cheaper than fresh input, but it is paid on every request, and the file still takes room in the context window.
Melta is free; join the waitlist.