Claude Code allow_large: How to Read Large Files
You ask Claude Code to review a big generated file or a long log, and it returns only the top part. Or it tells you to read the file in portions. That is the Read tool's size limits at work. Since Claude Code v2.1.296 (released October 9, 2026), the Read tool has an option built for this case: allow_large.
This guide explains what Claude Code allow_large does, how default file reading works, how to get Claude to use it, and when offset, limit, a search, or a subagent is the better choice. Everything marked as documented comes from Anthropic's official Claude Code documentation and changelog. Third-party reports are labeled as such.
Prefer video? The Hustle to AI channel covers the same topic here: https://www.youtube.com/watch?v=KrxZ7cRqWNU
What Is allow_large in Claude Code?
allow_large is an optional input on Claude Code's Read tool. The changelog describes it as letting Claude read a text file past the usual size limits in one call when it needs the whole file and the context has room. The official tools reference adds that Claude can read the whole file, or a long line range, in one call by setting allow_large to true. That read is sized against the room left in the session's context window instead of the default limits.
In plain terms: normally one Read call returns a limited amount of a file. With allow_large, Claude can ask for far more in one go, as long as your context window can hold it.
What to know before you rely on it:
Claude sets it, not you. The docs describe Claude setting allow_large: true when it needs to, for example because you asked for the entire file. I found no documented command-line flag or settings key that turns it on.
It needs v2.1.296 or later. Older versions do not have the option.
It applies to text files. Images, PDFs, and notebooks keep their own limits.
The context window is the real ceiling. The documentation does not state a fixed maximum file size for an allow_large read, so a file larger than your remaining context still cannot fit.
How Claude Code Handles Large Files
A file existing on disk does not mean Claude can see all of it in one response. Whatever Read returns goes into the model's context window, which is shared with your conversation, instructions, and earlier tool results. Default limits stop one careless read from filling it.
The documented defaults are:
One Read call returns at most 25,000 tokens by default. The CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS environment variable can change this value.
A whole-file read of a file over 256 KB is refused.
What Claude receives when a read goes over those defaults depends on how it asked:
Situation
What Claude gets
Whole file over the token limit
The first page of the file, with a PARTIAL view notice saying how much arrived and how to read more with offset and limit
Whole file over 256 KB
An error telling it to read a portion with offset and limit, or search with Grep
An offset or limit read over the token limit
The same kind of error, asking for a smaller range or a search
The PARTIAL view behavior is why a read can look successful while covering only the start of a file. According to a Claude Code docs issue, that change arrived around v2.1.145. Before it, an oversized whole-file read failed outright with a "file content exceeds maximum allowed tokens" error, which you will still see quoted in older tutorials and issue threads.
Surface differences (third-party report, check before relying on it). A March 2026 GitHub issue reported that the Claude Desktop app capped Read at 10,000 tokens while the command-line version allowed 25,000. The official tools reference does not mention a per-surface difference, so treat this as a user report that may have changed.
A common mix-up. The MAX_MCP_OUTPUT_TOKENS variable controls output from MCP servers only. The same GitHub issue reports that setting it does nothing for the built-in Read tool. For Read, the variable to look at is CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS.
How to Use Claude Code allow_large
Because Claude decides when to set the parameter, using it means making your intent clear.
Check your version. Run claude --version. You need v2.1.296 or later. Run claude update if you are behind.
Say you need the whole file. A request like this tells Claude that partial reads will not do:
I need the entire file read in one call, nothing omitted:
/path/to/schema.generated.sql
Summarize every table and flag missing foreign keys.
Check what came back. Look for a PARTIAL view notice or a truncation message. If you see one, Claude did not get the whole file.
Mind the context cost. A whole-file read stays in the session. If you only need one function or one error, do not ask for the whole file.
The Read tool's inputs include an absolute file path, the optional offset and limit, and allow_large. A whole-file read looks roughly like this (an illustration of the documented field names, not something you type):
{
"file_path": "/home/dev/project/schema.generated.sql",
"allow_large": true
}
Explicit wording matters in practice. A long GitHub issue titled "Need a way to enforce entire file reading" shows users getting partial reads on files as small as a few hundred lines, with a plain "read the entire file" instruction often fixing it and CLAUDE.md instructions described as unreliable. Some commenters suggested patching the minified CLI. That is unsupported and can break on every update, so do not do it. Ask in the prompt, and on v2.1.296 or later let Claude use allow_large.
Evidence From an Independent Test
Classmethod's developer blog published a hands-on test on Claude Code v2.1.296 using a 3,000-line text file of about 204 KB. Without allow_large, Read returned 732 of 3,001 lines and flagged truncation by the token cap. When the prompt said the entire file was needed, Claude set allow_large to true on its own and received all 3,001 lines in one call. The author reported the same behavior on Opus 5.5 and Haiku 5.5. The extra line is the empty line after the final newline.
Two cautions. This is one author's test, not a guarantee. And the file was under the 256 KB limit, so the token cap was what truncated it. The author also saw the full read cost less than the truncated one in that single-turn test, but that comparison should not be generalized to real sessions where the file then sits in context for every later turn.
Practical Examples for Reading Large Files
A large source file you need to review end to end
Read all of src/generated/api_client.py in one call and list every
public class and its methods.
If you only need one class, ask for that section instead.
A specific section of a long file
Read lines 1200-1400 of src/orders/processor.ts and explain the retry logic.
Here offset is the starting line and limit is how many lines to read. This works even when the whole file would exceed the defaults.
A 400 KB log file
A 400 KB log is over the 256 KB whole-file limit and, by the rough four-characters-per-token estimate, around 100,000 tokens. Even with allow_large you rarely want all of that in context. Search first:
Search app.log for "ERROR" and "timeout" and show the 20 lines around
the first three matches.
On macOS, Linux, and WSL the Grep tool is absent by default and Claude searches with grep and finds through Bash instead. Reading through Bash is not a way around limits: Bash returns about 30,000 characters inline by default, then saves longer output to a file and returns a path plus a short preview.
A large configuration file where every key matters
I need the complete config/production.yaml read in full. Compare it with
config/staging.yaml and list every differing key.
This is a reasonable allow_large case if both files fit comfortably in your remaining context.
A long PDF or a big notebook
allow_large does not change PDF or notebook limits. For PDFs longer than 10 pages, Claude reads in ranges using a pages parameter such as "1-5", up to 20 pages at a time. Page-range reads need pdftoppm from poppler-utils installed. A notebook whose cells exceed 256 KB or the token limit returns an error, and the error explains how to read a slice of cells with a shell command.
allow_large vs. offset and limit vs. Search vs. Subagents
Approach
Best for
Trade-off
allow_large
Tasks that truly need the whole file at once
Uses a lot of context; bounded by the context window
offset and limit
A known region, or paging through a big file
More calls; you need to know where to look
Grep or grep via Bash
Finding errors, symbols, or strings
You see matches, not the surrounding structure
Subagent
Heavy reading you do not want in the main conversation
You get a summary, not the raw content
A simple rule: if you can name what you are looking for, search. If you know where it is, use offset and limit. If the task needs everything and it fits, use allow_large. If the reading is heavy and you only need conclusions, hand it to a subagent, which has its own context window and returns only its final report.
Keep Your Context Healthy After a Big Read
A whole-file read can use a large share of the window. These built-in controls help:
/context shows how much of the context window is in use, so you can check before and after a big read.
/compact summarizes the conversation, optionally with instructions on what to keep. /clear starts fresh when you switch to unrelated work.
autoCompactWindow sets how full the context gets before automatic compaction. It accepts a number of tokens from 100,000 to 1,000,000, or "auto". Since v2.1.288 the /autocompact command saves this per model. v2.1.296 also lets a subagent set its own autoCompactWindow so it compacts earlier than the main conversation.
Read deny rules in settings.json keep Claude out of paths it should never open. A deny rule such as Read(./secrets/**) blocks reads entirely, and per the permissions docs it also blocks Edit and Write on that path, so use it only for files Claude should not touch.
One third-party guide suggests running /compact when usage reaches about 70 percent. Treat that as a rule of thumb, not an official threshold.
Community Tools for Very Large Files
allow_large helps when the file fits in context. For multi-gigabyte logs or datasets it will not, and some developers use MCP servers that read in chunks and search without loading everything. Examples include Large File MCP, whose author describes tools for chunked reading, regex search, and streaming, and pdf-mcp, which reads large PDFs incrementally by searching first and reading only the relevant pages. These are third-party projects, and their performance claims come from their authors. Review any MCP server before installing it, since it runs with access to your files.
Claude Code Limits vs. Claude Chat Limits
People often mix these up. The Read tool limits above apply inside Claude Code. The claude.ai chat has separate upload limits. A third-party summary of Anthropic's help center, dated October 2026, lists up to 20 files per chat, 500 MB per file, and PDFs up to 1,000 pages. Those figures change, so check Anthropic's help center. If you see a "message exceeds the length limit for this chat" error, that is the chat, not the Read tool, and allow_large will not fix it.
Troubleshooting
Claude only seems to have seen the top of the file. Look for a PARTIAL view notice. Ask Claude to continue with offset and limit, or say plainly that you need the whole file.
"Read a portion" or "search instead" errors. Your read exceeded a default limit. Use offset and limit with a smaller range, or on v2.1.296 or later ask for the whole file.
allow_large does not seem to exist. Run claude --version and update if it is below v2.1.296.
Claude will not use allow_large. It is Claude's decision. State that you need the entire file and accept the context cost. If the file is larger than your remaining context, ranges or search are the right call anyway.
Edits fail after a partial read. A read cut short by a PARTIAL view notice does not count for the read-before-edit rule on older models. Have Claude read the relevant part fully, then edit.
Garbled characters or refused edits. Edit and NotebookEdit refuse files that are not valid UTF-8, such as Shift-JIS or Windows-1252 text. This is separate from file size. The docs recommend a shell command that preserves the encoding, or converting the file to UTF-8 first.
Raising the limit did not help. MAX_MCP_OUTPUT_TOKENS affects MCP output only. Use CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS for the Read tool.
Frequently Asked Questions
What does allow_large do in Claude Code?
It lets the Read tool return a whole text file, or a long line range, in one call beyond the default limits, sized against your remaining context window.
Which version added it?
Claude Code v2.1.296 or later.
Can I turn it on with a flag or setting?
I found no documented flag or setting. The docs describe Claude setting it when needed, for example when you ask for the entire file.
What are the default Read limits?
25,000 tokens per call by default, adjustable with CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS, and whole-file reads over 256 KB are refused.
Does it work on PDFs, images, or notebooks?
No. Those keep their own limits.
Is there a maximum file size with allow_large?
The official docs I reviewed do not give one. The practical limit is your context window.
Is it better than offset and limit?
Only when the task needs the whole file at once. For a known region or a specific error, offset, limit, or search costs less context.
Conclusion
allow_large solves a specific problem: Claude needs an entire text file and the default limits get in the way. It is useful, but it is not magic. It needs Claude Code v2.1.296 or later, applies only to text files, and is bound by your context window. For most debugging, offset, limit, and targeted search still cost less. Match the method to the task and you will spend less context and get better answers.
Top comments (0)