Codex and AGENTS.md: every file from root down, and a 32 KiB cutoff

2026-09-21 · 5 min read codex codex cli agents md monorepo configuration ai coding agents

Codex does not pick the nearest AGENTS.md. It concatenates every file from your repo root down to the current directory, lets later files win conflicts, and stops at 32 KiB, which means the most specific instructions are the first to be cut. How discovery works, what AGENTS.override.md is for, and how to check what actually loaded.

A common explanation of AGENTS.md is that "the nearest file wins": a subdirectory's AGENTS.md replaces the one at the root. For Codex, that is not what happens, and the difference matters as soon as a repository has more than one of these files.

Codex concatenates. It loads every AGENTS.md from the project root down to your current working directory, joins them with blank lines, and passes all of it to the model. A file closer to your working directory wins only where two instructions conflict, and it wins because it comes later in the text, not because the earlier files were dropped.

We checked this in two places. OpenAI's documentation describes the merge explicitly. The system prompt built into Codex CLI 0.147.0 says the same thing: "The contents of the AGENTS.md file at the root of the repo and any directories from the CWD up to the root are included with the developer message". It follows with "More-deeply-nested AGENTS.md files take precedence in the case of conflicting instructions." Precedence applies to conflicts. It does not remove the other files.

The discovery order

Codex builds one chain of instructions in this order:

Global. It checks ~/.codex/AGENTS.override.md, then ~/.codex/AGENTS.md, and uses only the first non-empty one.
Project, from the root down. Starting at the project root, which is usually the Git root, Codex walks toward your current working directory. In each directory it looks for AGENTS.override.md, then AGENTS.md, then any fallback filenames you configured.
Merge. The files are concatenated root-first and separated by blank lines. Files closer to your working directory come later, so they win when instructions conflict.

Each directory contributes at most one file. AGENTS.override.md exists for the case where you need different guidance temporarily, or in one checkout, without editing the shared AGENTS.md that everyone else uses. When an override is present, the regular file in that same directory is not read.

The 32 KiB cutoff removes the most specific file first

This part is not in most explanations, and it causes real problems in large repositories.

project_doc_max_bytes defaults to 32 KiB. The docs say Codex "skips empty files and stops adding files once the combined size reaches the limit". Now combine that with the walk order. Codex adds files starting at the root. If the root AGENTS.md and a couple of intermediate files already fill the 32 KiB, the files closest to your working directory never get added.

Those are the files with the most specific instructions, the ones you wrote because this service or package does things differently. They are the first to be cut, and nothing tells you it happened.

Two ways to stay under the limit:

Keep the root file small. Put only repository-wide rules there. Every byte in it reduces what the more specific files can use.
Move procedures out of AGENTS.md. A multi-step procedure fits better as a skill, which costs about a line in context until Codex decides it needs it. See the Codex skills post for how skills are loaded.

If you really need more space, you can raise the limit in ~/.codex/config.toml:

project_doc_max_bytes = 65536

Raising it keeps the nested files, but everything that loads is sent with every request, so it has a cost too. Trimming the root file is usually the better fix.

Subdirectories below where you started

The chain covers directories from the root down to your working directory. It does not include directories below it. Codex's system prompt tells the model: "When working in a subdirectory of CWD, or a directory outside the CWD, check for any AGENTS.md files that may be applicable."

So if you start Codex at the repository root and it edits files in services/billing/, the instructions in services/billing/AGENTS.md are not part of the initial chain. The model is expected to go and read that file itself. It usually does, but that step depends on the model following an instruction, not on something Codex guarantees. When a directory's rules really matter, start Codex from that directory, so its file is part of the chain from the first request.

The system prompt also defines what each file covers: "The scope of an AGENTS.md file is the entire directory tree rooted at the folder that contains it." Direct instructions from you in the prompt take precedence over any AGENTS.md.

Other filenames and a different root

If your repository already has an instructions file under another name, Codex can read it without you renaming it:

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

Fallback names are checked only when a directory has no AGENTS.override.md and no AGENTS.md. project_root_markers changes what counts as the project root, which matters if your root is not a Git root, for example a directory inside a larger repository where you only want part of the tree considered.

Both settings go in your user config. Project-level .codex/config.toml files only load for projects you have trusted, a rule covered in the Codex config post.

Checking what actually loaded

The documentation suggests asking Codex directly:

codex --ask-for-approval never "Summarize the current instructions."

Codex should repeat back your guidance in precedence order. Run this after any change to a nested AGENTS.md. If an instruction from a deep directory is missing from the summary, the 32 KiB cutoff is the first thing to check.

To start a new file, run /init inside Codex. Its built-in instructions tell it to check whether an AGENTS.md already exists in the current directory first, and to leave it alone if one does.

Where AGENTS.md also matters

Code review. Codex reads a ## Code Review Rules section in AGENTS.md, from the root file plus the file closest to the changed code. See the Codex code review post.
Approval review. The review model that checks risky actions during a session treats AGENTS.md files as trusted, in the same category as your own messages. Its built-in instructions list "user and developer messages from the transcript, AGENTS.md files, and responses to the request_user_input tool" as the trusted content. Anything committed to AGENTS.md is effectively something you told the agent yourself, so review changes to it as carefully as you review code.

How this compares with Claude Code

Claude Code reads CLAUDE.md, not AGENTS.md, and it also concatenates every file it finds from the filesystem root down. So both tools combine files instead of replacing them. The real difference is conflict handling: Codex's system prompt tells the model that deeper files win, while Claude Code gives the model no ordering rule for conflicting instructions. The bridge between the two formats is covered in the AGENTS.md vs CLAUDE.md post.

Summary

Keep the root AGENTS.md short and limited to rules that apply everywhere. Put rules for a specific directory in that directory. Move procedures into skills. Start Codex from the directory whose rules matter most. After changing a nested file, ask Codex to summarize its instructions, because the most specific files are the ones the 32 KiB cutoff drops first, and Codex does not report when that happens.