Codex AGENTS.md: the hierarchy, overrides and size cap.

Codex builds its instructions from AGENTS.md files each time it starts a run. Knowing the order, the override file and the size cap explains most cases where Codex seems to ignore a rule.

Where Codex looks

Your Codex home (~/.codex by default, or the folder named by CODEX_HOME). It uses AGENTS.override.md if that exists and is not empty, otherwise AGENTS.md. Only the first non-empty file at this level is used.
The project. Starting at the project root (normally the git root), it walks down to your current folder. In each folder it checks AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames, and includes at most one file per folder.

The files are joined from the root down with blank lines between them. Files closer to where you are working come later, so they override earlier guidance. Empty files are skipped.

~/.codex/AGENTS.md                      personal rules (AGENTS.override.md wins if present)
my-repo/AGENTS.md                       repo-wide rules
my-repo/services/billing/AGENTS.md      billing rules
my-repo/services/billing/AGENTS.override.md   replaces the file above for this folder

Codex started in my-repo/services/billing reads, in order:
  1. ~/.codex/AGENTS.md
  2. my-repo/AGENTS.md
  3. my-repo/services/billing/AGENTS.override.md   (AGENTS.md is skipped here)

What the override file is for

AGENTS.override.md takes precedence over AGENTS.md in the same folder, and removing it restores the base file. That makes it a good fit for a temporary change, such as a stricter rule set during a migration, that you do not want to merge into the committed file. It replaces rather than adds, so copy what you still need into it.

The size cap

project_doc_max_bytes limits the combined size, 32 KiB by default. Once it is reached Codex stops adding files. Because files are added from the root down, the cut falls on the most specific, nested files, which are often the ones you wanted. Keep the root file short, or raise the limit.

# ~/.codex/config.toml
project_doc_max_bytes = 65536
project_doc_fallback_filenames = ["CLAUDE.md"]

Fallback names let Codex read a file it would otherwise ignore. With the setting above, a folder that has a CLAUDE.md but no AGENTS.md contributes its CLAUDE.md. Names not on the list are ignored, and a folder that has an AGENTS.md uses that instead. Restart Codex after changing the config, since the instruction chain is built once per run.

How this compares with Claude Code

Claude Code loads CLAUDE.md files from your personal folder, the project and its parent folders, with subfolder files loading on demand. Recent versions can also read AGENTS.md: by default only when there is no CLAUDE.md in the working directory or above it, with a setting to read both. Check your version's documentation. The dependable way to share one file is a CLAUDE.md that imports AGENTS.md with an @AGENTS.md line, or generating both from one source, as in sharing one rule set.

Keep it under the budget

The cap is a ceiling, not a target. A file that fits the 32 KiB limit can still be too long to follow. Aim for about 3,500 estimated tokens per engine and see why long instruction files get ignored.

Check your own files

Paste your CLAUDE.md or AGENTS.md into the free footprint scorer, or get the free sample and run rig doctor --lite locally. The hosted doctor check is A$0.50 a run and scores the whole setup, hooks included. The kit (A$10 once) has the rule source, generator, hooks and protocols these guides describe.