Source: Custom instructions with AGENTS.md (OpenAI Codex docs)
How Codex discovers, orders and size-limits AGENTS.md files (global, root-to-cwd, override and fallback names, 32 KiB default cap).
Contents
- What: official product documentation
- Publisher: OpenAI
- Date: living document, read 2026-11-14
- Original: Custom instructions with AGENTS.md (now served from learn.chatgpt.com)
Summary
Documents the exact instruction-chain algorithm Codex uses to build its project guidance, and how to verify it.
Key claims
- Global scope:
~/.codex(orCODEX_HOME);AGENTS.override.mdif present, elseAGENTS.md; first non-empty file only. - Project scope: walk from the project root (usually the git root) down to the working directory; in each directory include at most one of
AGENTS.override.md,AGENTS.md, then names inproject_doc_fallback_filenames. - Files are concatenated root-down with blank lines; closer files appear later and so override earlier guidance. Empty files are skipped.
project_doc_max_bytesdefaults to 32 KiB; once the combined size reaches it, further files are not added. Remedy: raise the cap or split into nested files.- The chain is rebuilt every run (no cache). Verify with
codex --ask-for-approval never "Summarize the current instructions.", or--cd subdirto test nested overrides.