How Codex reads AGENTS.md, and how to layer it so the right rules win
Global defaults, repo rules and per-service overrides stack in a fixed order. Know it, and a monorepo stops fighting your instructions.
Codex reads instructions from AGENTS.md files before it starts work, and it doesn’t read just one. It builds a chain of them, in a documented order, and the order decides which rule wins when two disagree. If you’ve ever had Codex ignore a rule you were sure you’d written down, the layering is the first place to look.
The details below come from the Codex AGENTS.md documentation .
The order
At the global level, Codex looks in ~/.codex/ and uses AGENTS.override.md if it exists, otherwise AGENTS.md.
At the project level, it walks from the Git root down to your current directory. In each directory it checks for AGENTS.override.md, then AGENTS.md, then any fallback filenames you’ve configured.
Everything found is concatenated from the root down and joined with blank lines. Because files closer to your working directory appear later in the combined prompt, they override earlier guidance. In short, the last file in the chain has the final say.
A layout that uses it
Say a monorepo with a payments service that has stricter rules than everything else:
~/.codex/AGENTS.md personal defaults
repo/AGENTS.md repo-wide rules
repo/services/payments/AGENTS.override.md payments-only rules
Keep the global file about you, not any project:
## Working agreements
- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.
Put team-wide expectations at the repo root:
## Repository expectations
- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.
And the exceptions next to the code they apply to:
## Payments service rules
- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.
Work from inside services/payments/ and Codex loads all three, with the payments rules last. The test command from your global file and the one from the payments file now conflict, and the payments one wins because it comes later.
Two ways this goes wrong
First, size. The docs say Codex stops adding files once the combined size reaches project_doc_max_bytes, which defaults to 32 KiB, and that larger content truncates silently. Silently is the word to notice. A bloated root file can push your nested rules out of the prompt with no error. Keep the root file short and move specific rules down into the directories they apply to.
Second, masking. An AGENTS.override.md always takes priority over AGENTS.md in the same directory, which means the base file is no longer read there. That’s what overrides are for, but if someone adds one to quiet a single rule, they may also be silencing everything else in the file it replaced.
Check what actually loaded
Don’t guess. Ask Codex what it sees, from the directory you care about. The docs give this command:
codex --ask-for-approval never "Summarize the current instructions."
Run it from the repo root, then again from services/payments/, and compare. The docs also note the chain is rebuilt once per run, so if instructions look stale, restart Codex.
Other filenames
If your team already keeps instructions under a different name, add it as a fallback in ~/.codex/config.toml:
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536
Raising the byte limit is possible, but it’s a patch for a file that’s grown too big. Every line in these files is read on every run, so each one should change what the agent does.
Next step: run the summarize command from two different directories in your own repo and see whether the answers differ the way you intended.