How Big Can AGENTS.md and CLAUDE.md Get?

Codex has the only limit most people will actually hit. It walks from the project root down to your working directory, takes at most one AGENTS.md per folder, and concatenates them. The Codex AGENTS.md guide says it stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default.

What the guide does not dwell on is what happens at the boundary. In agents_md.rs the file that crosses the budget is truncated, and the only signal is a log warning. Because the budget is spent from the root down, the file that gets cut is the deepest one: the folder-specific instructions closest to the code you are changing.

Two more details matter. Codex does not load AGENTS.md files below your working directory at all; its base instructions tell the model to look for them when it works there. And it never reads CLAUDE.md unless you list it in project_doc_fallback_filenames. You can raise the limit in config.toml; the docs' own example is project_doc_max_bytes = 65536.

Claude Code's hard limit is generous. Its memory documentation says it loads a CLAUDE.md of up to 4 MiB in full and skips a larger file. Note the word skips: a file over the limit is not trimmed, it disappears.

The limit you should care about is the recommended one: under 200 lines per CLAUDE.md, because longer files consume more context and reduce adherence. Claude Code warns at startup when a file is over the recommended length. The frequently quoted 200 lines or 25KB figure is real, but it belongs to the auto-memory MEMORY.md index, not to CLAUDE.md.

Claude Code now reads AGENTS.md itself, from v2.1.277, but by default only when there is no CLAUDE.md in your working directory or above it, and a CLAUDE.local.md counts. Add a personal local file and your AGENTS.md quietly stops loading. If you want both, there is a setting that loads them together, or a one-line @AGENTS.md import in CLAUDE.md.

Nested files are loaded on demand: a subdirectory's CLAUDE.md arrives once Claude reads, writes or edits a file in that folder, and rules with paths: frontmatter load when Claude touches a matching file.

Windsurf, whose documentation now lives under Devin Desktop, is the only other agent here with a published character limit: 12,000 characters per workspace rule file and 6,000 for the global rules file. The docs do not say what happens past it, so treat 12,000 as a wall. A root AGENTS.md is always on; one in a subdirectory applies only when Cascade reads or edits files under it.

Cursor documents no hard cap and recommends keeping rules under 500 lines. Two behaviours are worth knowing: a CLAUDE.md is applied to every conversation regardless of alwaysApply, and an @file reference inside a rule is not inlined, the agent reads that file only when it decides it needs it.

GitHub's code review guide suggests limiting any single instructions file to about 1,000 lines, beyond which response quality may deteriorate. Older posts quote a 4,000-character cap for Copilot code review; we could not find it in GitHub's current documentation. For the cloud agent, the nearest AGENTS.md in the tree wins. In VS Code, nested AGENTS.md support is behind chat.useNestedAgentsMdFiles, which is off by default.

Gemini CLI reads GEMINI.md from your workspace and its parents at startup, and loads more just in time when a tool touches a folder. We found no size cap in its docs or its memory discovery code, and everything it finds is sent with every prompt. It reads AGENTS.md only if you add it to context.fileName.

OpenCode reads AGENTS.md, falls back to CLAUDE.md, and reads each file whole. When its Read tool opens a file, it attaches instruction files found near that file. No cap means nothing is cut, and also that nothing stops the file from growing until every turn pays for all of it.

The usual fix for a long instruction file is to split it with imports. In Claude Code, @path imports reach at most four hops, and the docs are explicit that imported files load at launch, so splitting helps organisation but not context. Gemini CLI imports reach five levels and are likewise concatenated. Codex and OpenCode do not parse imports at all, and Cursor's @file is a pointer the agent may or may not follow.

So an import tree is the same file in more pieces. The only structure that changes what the agent reads is one that loads a piece when the agent is working where that piece applies: nested files, path rules, globs.

Few teams will hit 4 MiB. Many will hit the point where the file is read on every step and weighed on none of them. That point is measured in cost and adherence, not bytes.

We measured it. In PathruleBench, the same agent works through the same eight sessions while the team's knowledge grows from 500 to 2,000 items. CLAUDE.md files are read whole on every step. At 2,000 items, delivering the same knowledge by path instead cost about 55% less per chain and read 2.7 times fewer input tokens, and the agent passed more of the memory probes. At 500 items a plain file is cheap to read and hard to beat; the gap opens from about 1,000.

That is the idea behind Pathrule: keep a short root file for what really applies everywhere, and put the rest at the path where it applies, so each agent receives the slice for the code it is touching. Whatever tool you use, the checklist above tells you how much of your file is arriving today.