AGENTS.md too large: what Codex cuts off and how to split it
Codex reads AGENTS.md files up to a combined size, project_doc_max_bytes, which is 32 KiB by default. It adds files from the repo root down to your working directory and stops once the chain reaches the cap. The files nearest your working folder are added last, so they are the ones at risk. The fix is a shorter chain: cut what the agent can read from the code, nest files per folder, and move task-specific notes into files it opens only when needed.
Updated 2026-11-11
How Codex builds the chain#
Codex builds its instructions once when a session starts. OpenAI’s AGENTS.md guide describes the order:
- Your user file. In your Codex home folder, Codex reads
AGENTS.override.mdif it exists, otherwiseAGENTS.md. Only the first file that is not empty is used. - The project files. Starting at the project root, usually the Git root, Codex walks down to your current working directory. In each folder it looks for
AGENTS.override.md, thenAGENTS.md, and takes at most one file. - The join. The files are joined from the root down. A file closer to your working directory comes later in the text, so its rules take precedence.
Nothing in this chain loads on demand. Whatever makes it in is sent with each request for the rest of the session.
The cap, and what gets left out#
Codex stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default. Because the walk goes from the root down, a large file at the root can use the whole budget before Codex reaches the folder you are working in. The rules you wrote for that folder are then the ones the agent never sees.
An override file can hide instructions too. An AGENTS.override.md in a folder replaces that folder’s AGENTS.md completely. If someone left one behind, the regular file next to it is not read.
How to see what loads#
- Check the sizes. Add up the bytes of your user file and each AGENTS.md from the repo root to the folder you start Codex in. If the total is near the cap, you are at risk.
- Ask the agent. In a new session, ask Codex to list the instruction files it was given. A rule that should be there and is not points to the cap or an override.
- Use a map.
minnimemory initprints the chain for the folder you run it in: each file, its size, whether it loads, and the cap in force.doctorflags a file past the cap and an override file hiding anAGENTS.md.
Five ways to get back under the cap#
1. Cut what the agent can find itself#
Folder layouts, lists of dependencies and descriptions of what each file does can be read from the repo. Keep what the code cannot tell the agent: the commands to run, the rules that are not obvious, the things it must never do.
2. Nest files per folder#
Put the rules for one service or package in an AGENTS.md inside that folder. A session started elsewhere does not load it. OpenAI suggests this for larger projects.
3. Move task-specific notes out#
A release checklist or a database migration guide is needed on a few turns, not all of them. Put each in its own file and leave one line in AGENTS.md that says when to open it. The agent reads it when the task calls for it.
4. Raise the cap#
You can set a larger project_doc_max_bytes in your Codex config. It stops the cut, but it does not make the chain cheaper: every byte is still sent with each request.
project_doc_max_bytes = 655365. Split it with a tool#
MinniMemoryMCP does fixes 1 to 3 for a chain that is over the cap. It sorts each file into a small part that stays in AGENTS.md and files Codex opens only when a task needs them. Every line is kept, the originals are backed up first, and one undo puts the whole chain back.
$ npm i -g minnimemory
$ minnimemory install --host codexThen run /hooks once in Codex to trust its two hooks, and ask Codex to run init. A file Codex already loads whole is left as it is, because in our tests splitting a small file cost recall.