TL;DR When Claude needs to see a whole file (a log, a spec, a CSV), tell it to read "the whole file in a single Read call": it sets the Read tool's
allow_largeoption and loads it in one go if it fits, up to about 133,000 tokens in a fresh session. If you're after one line, ask it to search: 4,359 new tokens against 80,363.
Read returns at most 25,000 tokens per call and won't open a file over 256 KB in one piece. Past that, Claude walks the file in pages with offset and limit, one API request per page. Since v2.1.296 it has allow_large, which sizes the read against the context you have left instead of those caps. But it won't reach for it on its own: the error itself tells it to do so only if it needs the whole file or you asked for it.
What Claude gets when the file doesn't fit
It depends on the size. With a 128 KB log of 1,700 lines (73,330 tokens), under 256 KB, Read doesn't fail: it returns the first 492 lines with a PARTIAL view notice telling Claude to page through and not to answer from that page alone.
With a 301 KB log of 4,000 lines, the whole-file read fails with an error, not a page. This is what Claude received on v2.1.329:
File content (301.2KB) exceeds maximum allowed size (256KB). Use offset and limit
parameters to read specific portions of the file, or search for specific content
instead of reading the whole file. To read it anyway, up to what still fits in your
context, call Read again with allow_large: true — only if you genuinely need all of
it or the user asked for the whole file.
All you see is Read 1 file · 1 failed. And asked "which invoice failed to charge in app.log", Claude did not set allow_large: it tried 1,000 lines, hit the 25,000 tokens again (File content (43092 tokens) exceeds maximum allowed tokens (25000)), and read the file in eight pages of 550.
What each way of reading costs
Same question on the 128 KB log, Sonnet 5.5 in -p runs on v2.1.329. New tokens are input_tokens plus cache_creation_input_tokens, summed over every request in the run:
| How it read | Calls | Requests | New tokens | Re-read from cache |
|---|---|---|---|---|
| In pages, nothing asked | 4 Read |
5 | 80,978 | 154,635 |
| "The whole file in a single Read call" | 1 Read with allow_large |
2 | 80,363 | 6,184 |
With Grep available, nothing asked |
2 Grep |
3 | 4,359 | 15,842 |
allow_largedoesn't save the file: it goes in whole either way, about 80,000 tokens. What it saves is the round trips: every page is one more request that re-reads everything before it from cache, and on the 301 KB log that came to 11 requests and 757,629 tokens re-read.- A page isn't the file. If Claude answers from the first one, the invoice on line 1,650 doesn't exist for it. A single read leaves no such gap.
- For one line, searching wins 18 to 1. If the answer lives in one part, nothing should be read whole.
How to ask for it
1. Say you want it whole, in a single read
Read app.log, the whole file in a single Read call, and tell me which invoice failed to charge
With that phrasing, Sonnet 5.5 called Read with allow_large: true straight away. When the prompt only asked for the whole file, with no single read ("Lee app.log entero" in a Spanish run), it made a normal read, got the partial page, and asked for the rest, from line 493, with allow_large: two calls instead of four.
2. Check that it fits
The room isn't the whole window. Per the v2.1.329 binary, it's 70% of what you have left up to a ceiling, which in this container was 200,000 tokens even though Sonnet 5.5 had 1M, and every large read in the same turn shares it. In a fresh session it came to 133,436 tokens in the terminal and 136,813 in -p. The 301 KB log weighs 183,377 tokens and didn't make it:
File content (183377 tokens) exceeds maximum allowed tokens (133436). Use offset and
limit parameters to read specific portions of the file, or search for specific
content instead of reading the whole file. Even with allow_large, this is more than
fits in the context you have left this turn (other large reads in the same turn
share that room).
If the read was for the whole file, with no range, there's no error: the usual first page arrives, 463 lines, and the notice says how much room it had (allow_large had room for 136813 tokens this turn). A log like this runs at about 600 tokens per KB; plain prose weighs less. Before asking for something big in a long session, check what's left with /context or start a new one.
3. If you need one part, ask it to search
"Find the failed charge in app.log" leads to Grep, or ask for the range: "read lines 1600 to 1700". That's the gap between 4,359 tokens and 80,363 in the table, and the same thing that makes each re-read of an unchanged file cheaper.
4. Raise the per-call cap only if you always need it
CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS changes the 25,000 tokens of every read, including the ones Claude makes on its own, so every page grows and fills the context sooner. The 256 KB whole-file limit doesn't move with it. For one specific file, step 1 is enough.
Reference
| Limit | Default | When you pass it | With allow_large |
|---|---|---|---|
| Tokens per call | 25,000, or CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS |
Whole file: first page with PARTIAL view. A range: error |
Up to the turn's room |
| Whole-file size | 256 KB | Error | Up to what fits in the room |
| Context room | 70% of what's left up to the ceiling (here, 200,000), per turn | Doesn't apply | Error, or the first page if it read the whole file |
| Images, PDFs and notebooks | Their own limits | Their own error | Changes nothing |
Official docs: Tools reference: Large files
Requirements
- Claude Code v2.1.296 or later for
allow_large. Measured on v2.1.329 with Sonnet 5.5, in-pruns and in a terminal session, on 128 KB and 301 KB test logs.