Why Codex reads only part of AGENTS.md: project_doc_max_bytes and fallback file names
How Codex discovers AGENTS.md (search order, AGENTS.override.md, the 32 KiB default cap, fallback names) and how project_doc_max_bytes and project_doc_fallback_filenames change it.
Contents
You wrote detailed guidance in AGENTS.md, yet the later sections seem to have no effect. Or your team already maintains CLAUDE.md or TEAM_GUIDE.md and does not want another file just for Codex. Both come down to how Codex discovers and sizes AGENTS.md.
In short: Codex concatenates AGENTS.md files from the repository root toward the current directory and stops adding files once the total reaches 32 KiB by default. The limit is project_doc_max_bytes, and alternative file names go in project_doc_fallback_filenames.
KEY POINT
What you will learn
- The search order (global, then project) and the role of
AGENTS.override.md - How the 32 KiB cap applies and how to change it
- Using
project_doc_fallback_filenamesto readCLAUDE.mdor other names instead
Search order and concatenation
According to the docs, Codex gathers instruction files in this order.
- Global:
~/.codex/AGENTS.override.mdif it exists, otherwise~/.codex/AGENTS.md. Only the first non-empty file at this level is used - Project: from the Git root down to the current directory, checking each level for
AGENTS.override.md, thenAGENTS.md, then the fallback names - Files are concatenated from the root down, joined with blank lines. Files closer to the current directory appear later, so they override earlier guidance
Empty files are skipped, and the search stops at the current directory; AGENTS.md files below it are not read. Instructions are rebuilt on every run, so there is no cache to clear.
用語解説
AGENTS.override.md: a file used instead of AGENTS.md at the same level. It lets you keep the shared AGENTS.md untouched while adding your own overrides. Add it to .gitignore to keep it personal.
The 32 KiB cap
The total number of bytes read is capped by project_doc_max_bytes, which defaults to 32768 (32 KiB). When the cap is reached partway through concatenation, no further files are added. A large root AGENTS.md can therefore push a nearer, more specific AGENTS.md out entirely.
# Default is 32768. Raise only as much as you need
project_doc_max_bytes = 65536| Item | Value |
|---|---|
| Default | 32768 bytes |
| Applies to | the combined global and project instruction files |
| When exceeded | files after the point where the limit is reached are not added |
Before raising the cap, shorten AGENTS.md. Procedures you do not need every turn can live in a separate file that AGENTS.md tells Codex to read when relevant; Codex can open it during the task.
Changing the file names
List alternative names in project_doc_fallback_filenames. Codex tries them, in order, in any directory without an AGENTS.md.
project_doc_fallback_filenames = ["CLAUDE.md", "TEAM_GUIDE.md", ".agents.md"]A repository that keeps its guidance in CLAUDE.md for Claude Code then works for Codex too. Because the per-directory order is AGENTS.override.md, AGENTS.md, then the fallbacks, the fallbacks are ignored wherever an AGENTS.md exists.
Claude Code does not read AGENTS.md
The reverse direction is not automatic. Claude Code reads only CLAUDE.md, so to share one instruction file, import AGENTS.md from CLAUDE.md with @AGENTS.md. The differences between the two tools' instruction files are part of Codex vs Claude Code.
Switching configuration directories
For CI or automation that needs different global instructions, point CODEX_HOME at another directory. $CODEX_HOME/AGENTS.md becomes the global instruction file, so keeping one directory per purpose is a clean way to separate them.
What to put in AGENTS.md in the first place is covered in Configuring Codex with config.toml, the hub article for this series.
Summary
- AGENTS.md files are gathered from
~/.codex/, then the Git root down to the current directory, and concatenated root first; nothing below the current directory is read - At each level
AGENTS.override.mdbeatsAGENTS.md - Past 32 KiB in total (
project_doc_max_bytes = 32768) no further files are added; shorten before raising project_doc_fallback_filenameslets Codex readCLAUDE.mdor other names instead- Separate
CODEX_HOMEdirectories give you per-purpose global instructions
FAQ
- How much of AGENTS.md does Codex read?
- Up to 32 KiB in total by default (project_doc_max_bytes = 32768). Files are concatenated from the root toward the current directory, and once the limit is reached no further files are added.
- Can Codex read a file with a different name?
- Yes. List candidates in project_doc_fallback_filenames; Codex tries them in order in any directory that has no AGENTS.md.
- What is AGENTS.override.md?
- A file that takes the place of AGENTS.md in the same directory. Use it for personal overrides or local experiments.
Primary sources
This article was drafted by AI from official documentation and reviewed by the site operator before publishing. Found a mistake? Let us know via the contact page.