# Codex's 32 KiB default would cut our 35,479-byte CLAUDE.md three bytes into a heading and drop its last 3 sections

> Source: <https://dev.to/rulestack/codexs-32-kib-default-would-cut-our-35479-byte-claudemd-three-bytes-into-a-heading-and-drop-its-cgp>
> Published: 2026-11-16 02:17:00+00:00

The `CLAUDE.md` at the root of our agent repo was 35,479 bytes at commit `f53fb172` on 2026-11-11. Claude Code loads all of it. Given to Codex as its project instructions, the same file would be cut at Codex's default `project_doc_max_bytes` of 32 KiB, exactly three bytes into a heading: Codex would keep `##` and lose the last 2,711 bytes, which hold the handover checklist, the rules for editing the file itself, and the emergency stop.

Running two coding agents on one repository is common enough, and the cheap way to keep them in step is one instructions file: a symlink from `AGENTS.md` to `CLAUDE.md`, an import in one direction or the other, or Codex's `project_doc_fallback_filenames` pointed at `CLAUDE.md`. The question we had not asked until this week is whether both agents read the same amount of that file. They do not, and the reason is a unit. Codex budgets project instructions in bytes. Claude Code's limits for instruction files, where it has them, are in characters, and the one file both of them read at startup has no Claude Code limit short of 4 MiB.

We did not run Codex against our file for this post. Everything on the Codex side below comes from its documentation and from the loader's source at the `rust-v0.167.0` tag, the release installed on our machine. The cut point is arithmetic on our file, done by a short script, and we say where each number came from.

The Codex guide describes the walk. Starting at the project root, it goes down to the working directory, and "In each directory along the path, it checks for AGENTS.override.md, then AGENTS.md, then any fallback names in project_doc_fallback_filenames." It concatenates what it finds from the root down, then "stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default)." The release's `defaults.toml` has the number: `project_doc_max_bytes = 32768`.

The guide's wording, "stops adding files", leaves open what happens to a file that is larger than the budget left over. The loader in `codex-rs/core/src/agents_md.rs` answers it. When a file's size is larger than the remaining budget, it calls `data.truncate(remaining as usize)` and keeps the first `remaining` bytes. It then turns those bytes into text with `String::from_utf8_lossy`, so a cut that lands inside a multi-byte character becomes a replacement character rather than an error. The budget is shared: every file loaded on the way down subtracts its length, so a long root file leaves less room for the nested ones that the guide suggests as a way to split instructions.

Two more details from the same code matter for anyone sharing a file. In the 0.167.0 release, the only signal on that path is a `tracing::warn!` line with the message `project doc exceeds remaining budget; truncating`. On the main branch on 2026-11-11, which is newer than that release, the loader also pushes a warning that starts `Loaded only {remaining} of {size} bytes from` and suggests raising `project_doc_max_bytes`. And a project that Codex has marked untrusted loads no project instructions at all; the function returns before the walk.

Claude Code's memory page splits instruction files into two groups. Files in the directory hierarchy above the working directory, including the project root's `CLAUDE.md`, load at launch, and for those the page is direct: "Claude gets the whole of each CLAUDE.md file that loads at launch, as long as the file is 4 MiB or smaller." Above the recommended length you get a warning at startup and in `/status`, not a cut.

The second group, `CLAUDE.md` files in subdirectories and path-scoped rules, loads on demand and does have a per-file cut. The page gives the numbers: 40,000 characters in a 200K context window, and 150,000 characters in a 1M window on models newer than Opus 4.6 and Sonnet 4.6. A file over the limit arrives as its start plus a note telling Claude to read the rest with the Read tool. The page dates that limit to v2.1.309, and the changelog for 2.1.317 has a related fix for sessions "whose very large CLAUDE.md changed since it was last sent", which used to hit "Prompt is too long" after automatic compaction. So Claude Code is not limit-free either; its limits sit elsewhere and count something else.

Characters versus bytes is where the two diverge for us. Our file is written mostly in Japanese, and in UTF-8 each of those characters is three bytes. At `f53fb172` the file had 18,470 characters and 35,479 bytes; 8,514 of the characters were outside ASCII. Measured the way Claude Code measures its on-demand files, the file is under half of the 40,000-character limit. Measured the way Codex measures, it is over the default budget by 2,711 bytes. An English-only file of the same character count would be about 18 KB and fit in either.

We wrote a short script that reads the file at the commit, keeps the first 32,768 bytes the way the loader would, decodes them the same lossy way, and reports the line, the section and the byte offset of the cut. Line 234 is the heading of section 15. That heading line starts at byte 32,765, so the kept text ends with the first three bytes of it, `##`, and nothing after. The cut does not split a character, because those three bytes are ASCII.

What would be lost, in order: section 15, a checklist for whoever picks up the work (only its `##` survives); section 16, the rules for editing the file itself, which include where the size limits live; section 17, how to stop the agent and its scheduled jobs in an emergency; and the footer with the last-updated date and version number. That is 1,503 characters of 18,470. As a share it is small. As a selection it is unlucky, because the end of the file is where we had put the rules about the file and the stop switch, on the theory that nobody needs them until something goes wrong.

`git log -- CLAUDE.md` lists 349 commits that touched the file, starting on 2026-05-26 at 19,294 bytes. Three days later, on 2026-05-29, it was 34,299 bytes, already past 32,768. It grew through the summer, with every rule, procedure and note about why a rule existed going into the same file, and reached 548,487 bytes on 2026-08-17. On 2026-08-18 it was split into skills, rules files and docs, and the first commit of that day brought it to 38,296 bytes. From September onward it has stayed between 32,542 and 44,992 bytes. Of the 349 versions, 327 were larger than Codex's default budget.

The split on 2026-08-18 came with a size check at 45,000 bytes for the whole file, and a cap of 35,000 bytes for everything above the footer followed on 2026-09-06. A test in the repository checks both caps on every commit. The source comment for the 45,000-byte cap gives the reason in one line: the file is loaded in full into every session, so growth is stopped at commit time. Those caps were chosen with Claude Code's context in mind. Neither of them is 32,768, and nothing in the repository compares the file against Codex's budget.

Three options, compared on what they cost and what they protect. We have not applied any of them to our file; this is the comparison, not a report.

**Raise the budget on the Codex side.** The guide shows `project_doc_max_bytes = 65536` in `~/.codex/config.toml` as part of its fallback example, and says that "The larger byte limit allows more combined guidance before truncation." It is one line and fixes today's file. It is also per machine: every person and every CI runner that uses Codex on the repository needs the same setting, and the repository itself cannot show whether they have it.

**Reorder the file so that a cut costs the least.** Put the rules whose absence is dangerous, such as how to stop the agent, near the top, and let the tail be the material that is safe to lose, such as reference tables. It costs nothing at load time and protects both agents, since a long file is also the one most likely to be skimmed. It does nothing for the cut itself, which will keep moving as the file grows.

**Move procedure out of the root file.** This is what the August split did for Claude Code: steps that only matter for one task live in files that load when that task starts. Codex's nested `AGENTS.md` files are the nearest equivalent, but they share the same 32 KiB budget on the way down, so moving text from the root file into a nested file only helps when Codex is started in a directory whose path skips some of them.

The cheapest step, whatever else you choose, is to measure. `wc -c` on your instructions file is the number Codex compares against 32,768. `wc -m` under a UTF-8 locale is the number Claude Code's per-file limits are written in. If the two differ by a factor of two, as ours do, a file that looks comfortable in one agent can be over the limit in the other.

`rust-v0.167.0`; a Codex build with different defaults or a user config with a different `project_doc_max_bytes` changes it.`f53fb172`.
How large is the instructions file that your agents share, in bytes and in characters, and has either agent ever cut it short for you? Please leave the numbers in the comments below.
