How long can AGENTS.md or CLAUDE.md be? The limit each agent enforces

A 45,000-character CLAUDE.md at the root of a repository loads in full in Claude Code, with a warning that it is longer than the recommended length. The same file in a subdirectory is over the 40,000-character limit for files that load on demand in a 200K context window (the text the model can see at once), so Claude sees only its start. Put it in front of Codex as AGENTS.md and the project chain is cut at 32 KiB, with the end of the deepest file the part that disappears. Same file, three answers.

The file has no size of its own. The AGENTS.md format is plain Markdown with no required fields, and the limit comes from the program that reads it. The six agents below do not agree on a number, and four document none at all.

Checked against each tool's documentation on 27 October 2026.

The limits, by agent#

Cursor's rules page says to keep rules under 500 lines, but that is guidance, not a documented hard cap. Cursor's own round covers its .mdc rules; this page does not.

The numbers are in different units#

200 lines, 40,000 characters, 32 KiB and 10,000 tokens measure different things. A line can be a word or a paragraph. A character is one byte only in ASCII. A token is a model-specific unit, and the common estimate of four characters per token is an estimate, not a definition.

A 200-line file of long paragraphs can be larger than a 32 KiB file of short bullets. A 32 KiB ASCII file is about 32,768 characters; the same byte count of non-ASCII text is fewer characters. Convert before comparing.

Claude Code: 200 lines is a target, 4 MiB is the skip#

The 200-line figure is a target, not a cap. The memory docs say longer files "consume more context and reduce adherence." A longer file still loads; Claude warns at startup and in /status when a file is over the recommended length, and warns at session start when several such files add up past a combined limit the docs do not quantify. The warning is a prompt to trim, not a refusal.

The hard skip is 4 MiB. A launch CLAUDE.md over 4 MiB is skipped and none of it loads. That is the only size at which Claude Code refuses a launch file.

The smaller limit is for files that load on demand: a subdirectory CLAUDE.md or CLAUDE.local.md, a path-scoped rule in .claude/rules/ (one that loads only when a matching file is in play), and their imports. On v2.1.309 or later, those are capped at 40,000 characters in a 200K window, 200,000 in a 1M window on Opus 4.6 and Sonnet 4.6, and 150,000 on later models. Over the cap, Claude gets the start and a note to read the rest with the Read tool; the rest is not in context until it does. Before v2.1.309, the cap did not apply to files that load on demand.

This is the 40,000-character limit people hit. A 45,000-character root file loads; the same file in packages/api/ at 200K is over 40,000 characters and is clipped.

Imports do not buy room: @path imports load with the importing file, up to four hops. Auto memory is a different limit: MEMORY.md loads its first 200 lines or 25 KB, while CLAUDE.md loads in full up to 4 MiB. The shared 200 lines is two different rules.

The docs state these numbers for CLAUDE.md. Claude reads AGENTS.md directly on v2.1.277 and later when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md is present in the working directory or above it. The docs give no separate limit for an AGENTS.md that Claude reads directly; it enters the same context.

Codex: 32 KiB for the project chain#

Codex's number is a budget, not a per-file allowance. The AGENTS.md page says Codex stops adding files once the combined size reaches project_doc_max_bytes (32 KiB by default). The advanced config page calls the same key "how much to read from each AGENTS.md file." The contradiction is tracked in #36371.

The code reports say the combined reading is the implemented one. #37956 reads the source: one shared 32 KiB budget, spent root-first, so the deepest file is the one cut; the cut truncates the file, so it loses its ending; the global file is outside the budget.

A 22.5 KB root file leaves under 10 KB for every file below it, and the rule at the bottom of a nested file is the first to go. Nothing in the normal transcript warns; #13386 reports the cut in the TUI, codex exec and the VS Code extension. An earlier ~40 KB report was closed as not planned in March 2026 (#7138).

Raise it if the chain is genuinely large:

# ~/.codex/config.toml
project_doc_max_bytes = 65536

Then start a new run. Measure every file on the root-to-current-directory path with wc -c and add the bytes. Under a shared budget, splitting across nested directories does not create room; it changes which file is cut.

The agents that document no number#

Gemini CLI, Copilot CLI, OpenCode and Qwen Code publish no size limit. That does not make the file free: each loads the applicable files into the prompt, so the bytes occupy the window and the window is the ceiling. None documents a truncation point; Qwen warns.

Gemini CLI. The GEMINI.md page states no limit. It concatenates the global file, workspace files and their parents, and just-in-time files when a tool touches a directory, so a long nested file can enter mid-session.

Copilot CLI. The custom-instructions page states no limit. All applicable user-level and repository files are combined, and duplicate copies of identical instructions are removed. There is no general precedence order.

OpenCode. Neither V2 nor V1 states a limit. In V2, a nested file is deduplicated while its instruction entry is in model-visible history; after a compaction or revert removes it, a later read can load the file again, so a long nested file can be sent twice.

Qwen Code. The memory page says shorter is better but states no numeric cap. At v0.26.2, the code warns when always-loaded context (context files plus auto-memory) is estimated above the smaller of 15% of the window and 10,000 tokens (config.ts). It is a warning, not a truncation, and the docs do not mention it.

A file under the limit still costs every request#

The limits say when a loader clips a file, not what it costs while under the limit. A 10 KB file below a 32 KiB cap is still 10 KB of the prompt on every turn.

The best evidence is a controlled study: Gloaguen et al., Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (arXiv:2602.11988v3, revised 29 September 2026). Across SWE-bench tasks with LLM-generated files and issues from repositories with developer-committed files, it found that providing context files "does not generally improve task success rates, while increasing inference cost by over 20% on average." That is an average across its models and tasks, not a constant. The extra cost came from the agents doing more — more steps, more tests — not from the length of the file: v3 reports "no clear dependency between the success rate or the per-instance cost and the context file length." The cost of length is arithmetic, not a study result: a 10 KB file is 10 KB of every prompt. The study also found repository overviews, a popular section in these files, were not helpful.

Claude Code's status line reports context usage but no per-file instruction count; a request for one was closed as not planned (#20639, March 2026). Codex warns nothing in the normal transcript (#13386). Qwen is the only one of the six that warns against a share of the window. Measure the file, then measure the prompt: a file that loaded is not necessarily earning its tokens.

Measure the file, then check the prompt#

Measure in the unit the limit uses:

wc -l CLAUDE.md   # lines
wc -m CLAUDE.md   # characters
wc -c AGENTS.md   # bytes

wc -m counts characters, not bytes; on UTF-8 they differ. For Codex, add the bytes of every file on the root-to-current-directory chain.

Then check the prompt, because the file on disk is not the file in the prompt. In Claude Code, /context lists the launch files under Memory files; a nested file or path-scoped rule appears when it loads, as the nested CLAUDE.md guide shows. In Codex, codex debug prompt-input prints the model-visible prompt; read the tail of the deepest file, as the Codex AGENTS.md guide shows. The other checks are in the Copilot CLI, Gemini CLI, OpenCode and Qwen Code guides, and the index is how to check what your agent remembered.

Where to go next#

• Why Codex ignores part of your AGENTS.md — the 32 KiB chain, the root-first cut, and the prompt dump.
• Why your nested CLAUDE.md never loaded — the on-demand limit and the trigger.
• Claude Code loaded your CLAUDE.md but isn't following it — when the file is in context and the model still ignores it.
• Do AGENTS.md files actually help? — the benchmark behind the cost figure.
• Persistent memory for Claude Code and Codex — the hub for the rest.