Where Codex looks for AGENTS.md
When it starts, Codex builds one chain of instructions: a global file, then project files along the path to your working folder.
1. Your global file. In the Codex home folder, ~/.codex (or the folder set by CODEX_HOME). Codex uses AGENTS.override.md if it exists, otherwise AGENTS.md. Only one file is used here.
2. Your project. Codex starts at the project root (the Git root by default; project_root_markers can change that) and walks down to the folder you are working in. In each folder it takes at most one file, checking in this order:
AGENTS.override.mdAGENTS.md- Any name you listed in
project_doc_fallback_filenames
If there is no project root, Codex checks only the current folder.
How the files combine
Codex joins the files from the root down, with blank lines between them. A file closer to your working folder comes later, so its instructions win over earlier ones. Empty files are skipped.
There is a size limit: Codex stops adding files when their combined size reaches project_doc_max_bytes, 32 KiB (32,768 bytes) by default. If your instructions are long, raise the limit or split them into AGENTS.md files in subfolders.
Both settings live in config.toml in your Codex home folder (by default ~/.codex/config.toml):
project_doc_fallback_filenames = ["TEAM_GUIDE.md"]
project_doc_max_bytes = 65536
Start a new Codex run after changing them.
A simple AGENTS.md
# AGENTS.md
## Commands
- Build: `npm run build`
- Test: `npm test`
## Rules
- Write plans to `docs/plans/<task>.md` before changing code.
- Keep each change small; explain it in the pull request.
Codex does not save plans to files on its own. To get plans you can read later, ask it to write one to a file, in AGENTS.md (like the second rule) or in your prompt.
Reading what Codex writes
With a few files, any editor works. With many (a plan per task, notes, reports), it helps to read them as pages and see what changed.
On a Mac, PilcrowMD (free, beta):
- Add your project folder in My folders. Files Codex writes show up marked N (new) or U (updated). An open note reloads when Codex or another app changes it.
- Highlight changes shows what Codex changed in a plan you already read: blue for added, orange for removed or edited.
- Compare side by side shows two versions, as the page or as the source.
- With file history on, File › Show History… lets you go back to an earlier version.
- Tables, code blocks, task lists and Mermaid diagrams are drawn as a page. No internet connection.
PilcrowMD for Mac (beta) · More on reading agent files
Common questions
Is AGENTS.md only for Codex? No. It is an open convention that several coding agents read, not a Codex-only format. Claude Code, for example, can read AGENTS.md when a project has no CLAUDE.md (Claude Code page).
Why does Codex ignore part of my instructions? Check the size limit (32 KiB by default) and whether an AGENTS.override.md in the same folder takes the place of your AGENTS.md.
Can I read these files on my phone? If the project folder syncs to Google Drive, add it in My folders in PilcrowMD for Android. Open a note to see its latest version; there is no live reload on Android.
Also on Mac: PilcrowMD for Mac (beta)