Why Codex ignores part of your AGENTS.md, and how to see what it loaded

AGENTS.md is a plain Markdown file of standing instructions. Codex reads it before it starts work, so a rule about tests, style, or a dangerous command does not have to be repeated in every prompt.

Codex does not read every AGENTS.md in the tree. At startup it builds one chain: a global file, then files from the project root down to the directory where you started it. It concatenates them into the prompt. A file that is not on that path is never loaded, and a file that falls beyond the size limit is left out of the prompt.

If you want the check before the explanation, run codex debug prompt-input in the directory where you start Codex. It prints the model-visible prompt as JSON; the section "Prove what reached the model" explains how to read it.

Checked against Codex's documentation on 26 October 2026.

Status, 26 October 2026: the size rule is still written two ways in the docs. The AGENTS.md page says one combined limit; the config pages say the limit applies to each file. Two open documentation issues describe the contradiction (#36371, #37956), and a separate open report tracks the silent cut (#13386, updated 24 October 2026). If your version has changed the wording or added a warning, the checks below still apply.

The chain Codex builds#

Discovery has two levels.

Global. In your Codex home — ~/.codex unless CODEX_HOME points elsewhere — Codex reads AGENTS.override.md if it exists, otherwise AGENTS.md. It uses only the first non-empty file at this level.

Project. Starting at the project root, usually the Git root, Codex walks down to your current working directory. In each directory on that path it checks AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames. It includes at most one file per directory. If it cannot find a project root, it checks only the current directory.

The files are joined from the root down, with a blank line between them. That order is the whole point: a file closer to your work appears later in the prompt, so it can add to or contradict the broader guidance before it.

Take a repository with a root AGENTS.md, a services/payments/AGENTS.override.md, and a sibling search/AGENTS.md:

repo/
  AGENTS.md
  services/
    payments/
      AGENTS.override.md
  search/
    AGENTS.md

Start Codex in services/payments and it reads the global file, the root file, and the payments override. Start it in search and it reads the global file and the root file, not the payments file. Start it at the repository root and it reads the global file and the root file only. A file in a directory you did not descend into is not part of the chain.

AGENTS.override.md replaces the regular file in the same directory; it does not add to it. That is why an override left behind after an experiment can make a folder seem to have no rules at all.

The 32 KiB limit applies to the project chain#

The setting is project_doc_max_bytes, 32 KiB by default. The AGENTS.md page states the rule: Codex stops adding files once the combined size of the project chain reaches the limit. Two config pages describe the same key as how much to read from each file. Two open documentation issues track the contradiction (#36371, #37956).

The project chain is assembled from the root down, so the budget is spent in that order. #37956, open and updated 18 August 2026, goes further than the docs: it reports that the file crossing the limit is truncated mid-file, so the deepest, most specific file can lose its ending. The docs say only that Codex stops adding files. Either way, files after the one that reaches the cap contribute nothing.

This is the failure people describe as "Codex ignores the rule I just added". The rule is often in a nested file at the end of the chain, behind a large root file. Nothing in the normal transcript says it was left out.

Raise the limit if the chain is genuinely large:

# ~/.codex/config.toml
project_doc_max_bytes = 65536

Then restart Codex. The chain is built once per run, and at the start of each terminal session.

The same report says the global file is loaded separately, outside the project budget. The docs do not state that, so treat it as the report's reading of the source.

Why a nested file never loads#

If the rule is not in the prompt at all, the cause is usually one of these.

• You started in the wrong directory. Codex walks from the project root to your current directory. Starting in a subdirectory loads more files than starting at the root, not fewer, but only along that one path.
• The file is in a sibling subtree. That is expected behaviour. An open feature request asks for dynamic loading of nested files in monorepos (#12115, open, activity on 26 October 2026); the current docs describe one file per directory on the root-to-cwd path.
• There is no project root. Without a Git root or a marker configured in project_root_markers, Codex checks only the current directory, so parent files are skipped.
• An override is holding the slot. The docs say Codex skips empty files. An open report says an empty AGENTS.override.md still claims that directory's slot and suppresses the AGENTS.md beside it (#54755, open, updated 24 October 2026). Delete the empty override rather than clearing it.
• The project is marked untrusted. The config docs say untrusted projects skip project .codex/ layers, including project config, hooks, and rules. One report says project AGENTS.md is skipped too; the docs do not list it. If the global file loads but the project files do not, check trust before editing files.
• You edited a different Codex home. CODEX_HOME moves the global file, the config, and the session store. Run echo $CODEX_HOME in the same shell that launches Codex.
• You are in the desktop app and the folder is secondary. The desktop app uses a project's primary folder for automatic discovery of AGENTS.md, skills, and config.toml. Other attached folders can be read and edited, but Codex does not scan them for project files.

There is also the case where the file did load and the model still did the opposite. That is not a discovery problem; it is an instruction problem. Make the rule concrete and testable, put it near the work it governs, and verify it with the quote test below.

Prove what reached the model#

/status is not enough. In the CLI it has an Agents.md line, but the open report shows it can go stale after /init creates a project file (#37704, open, updated 22 August 2026). It is not a reliable inventory of the chain; a <none> there is not proof that your global file was skipped.

The direct check is the model-visible prompt. The CLI has a debug command that renders the exact prompt input as JSON:

codex debug prompt-input

Run it from the directory where you start Codex. Search the output for the text of each file, not just its filename. If the last lines of your nested file are absent, the file was clipped. If the whole file is absent, it was never on the chain.

For a running terminal session, opt into the plaintext log:

codex -c log_dir=./.codex-log

Then read ./.codex-log/codex-tui.log. The docs name this as the audit route for instruction discovery. The log is the place a truncation warning would appear, if your build emits one.

A weaker but quick check is to ask Codex to quote the last line of the file you care about, without reading files. A model that can quote it has it in context. A model that paraphrases the gist may be working from a general impression rather than the exact line. The prompt dump is the evidence; the answer is only a hint.

Keep the chain inside the budget#

• Keep the root file short. Every byte there is a byte the nested files cannot use.
• Put universal habits in the global file, project conventions in the root file, and rules for one service in that service's file.
• Prefer one specific file on the path you actually work from over a large file in a directory you rarely enter.
• Measure before you raise the limit. Doubling project_doc_max_bytes helps only if the chain is the problem; it also puts more text in every prompt.
• After editing any instruction file, start a new run. The chain does not rebuild inside a running session.

Where to go next#

• Which config.toml Codex is actually reading — if the budget is not the problem, the settings layer is the next check.
• Context compaction — if a rule that loaded at the start seemed to fade during a long session.
• How long can AGENTS.md be? and one AGENTS.md for every agent — the documented byte limits, and how to share one file across tools.
• Codex guides — sessions, permissions, hooks, and the rest of the set.