Codex builds its instructions from a global file in your Codex home, then walks from the project root down to your current directory, reading at most one file per folder. Files are concatenated root first, so closer ones win. The combined size is capped at 32 KiB by default.
Global scope
According to the Codex documentation, Codex checks its home directory, ~/.codex or the path in CODEX_HOME. It reads AGENTS.override.md if that exists and is non-empty, and otherwise AGENTS.md. Only the first non-empty file at this level is used.
Project scope
Codex starts at the project root, typically the Git root, and walks down to the current directory. In each directory it checks, in order, AGENTS.override.md, then AGENTS.md, then any names listed in the project_doc_fallback_filenames setting. It includes at most one file per directory. If no project root is found, only the current directory is checked.
Precedence and the size cap
Files are joined from the root down, separated by blank lines. Files closer to your working directory appear later and override earlier guidance. Empty files are skipped.
The default project_doc_max_bytes is 32 KiB. Once the combined content reaches that limit, Codex stops adding files. That means a large root file can starve nested ones, with no error. The docs suggest raising the limit or splitting instructions into nested directories.
Settings
project_doc_fallback_filenames: alternate names such as a team guide file. Names not on the list are ignored.project_doc_max_bytes: the combined limit.CODEX_HOME: moves the global directory.
Restart Codex or start a new command after a config change.
Verify the chain
Do not assume your file loaded. The documentation suggests asking Codex to summarize the current instructions from the repo root, using the --cd option to test a subdirectory, and enabling a log directory to inspect the session file. Codex rebuilds the chain on every run, so restarting in the target directory refreshes stale instructions.
Practical layout
- Root file: build and test commands, conventions that apply everywhere. Keep it short.
- Nested files: rules specific to a service or package.
- Override file: for a temporary change, such as a release freeze, that you do not want to commit into the main file.
Not enforcement
Like other instruction files, this guides behavior. Approvals and sandbox settings, covered in the next posts, are what constrain actions. Memories, the docs add, are a recall layer, so required team guidance belongs in AGENTS.md or checked-in docs.
Quick check
How many AGENTS.md files does Codex read per directory?
At most one. It checks the override file, then AGENTS.md, then fallback names.
What happens when instructions exceed 32 KiB?
Codex stops adding files once the combined content reaches the limit, so later nested files may be left out.
Sources
Last reviewed: 19 October 2026.
