Make Codex Explain Which Instructions It Loaded
When Codex ignores a rule in AGENTS.md, check which instruction files it loaded before you add another rule. A new rule can make the conflict harder to see.
You need: the Codex CLI and a repository with at least one AGENTS.md. The command below runs
Codex in its read-only sandbox, so it can read files but not change them.
Ask from the directory where the task will run:
codex --cd services/payments --sandbox read-only --ask-for-approval never \
"List the instruction sources you loaded, in order."--ask-for-approval never only stops Codex from pausing to ask. It does not make a run read-only;
--sandbox read-only does.
Then open the named files yourself. The model's list is a lead, not proof. Codex's documented order is the global file in ~/.codex first, then at most one file per directory from the project root down to the working directory. Inside a directory, AGENTS.override.md wins over AGENTS.md. Files nearer the working directory come later in the prompt, so they take precedence.
The documented rules point to three causes to rule out:
- The task ran from a directory above the nested file, so Codex never looked there.
- An override file or the global file says the opposite.
- The combined files passed
project_doc_max_bytes, 32 KiB by default, and Codex stopped adding files.
To practice, put one harmless formatting rule at the root of a scratch repository and a different rule in a nested folder. Run the command from both places. If discovery works as documented, the root run lists your global file first, if you have one in ~/.codex, and then the root file. The nested run lists the global file, then the root file, then the nested file last. Record the intended scope in the repository so a colleague who starts from another directory gets the same result.
For a record that does not depend on the model's answer, the documentation describes a plaintext log: start Codex with -c log_dir=./.codex-log and read codex-tui.log.
What was checked: --cd, --sandbox, --ask-for-approval, and -c appear in the help output of codex-cli 0.155.1, run on September 20 and 21, 2026. The discovery order, the size cap, and the log option come from OpenAI's documentation read the same day. Neither the command nor the practice exercise was run against a live model for this note, so the expected listings above are the documented behavior to test for, not observed output.
Next: if the right files load and Codex still misses a rule, test whether a shorter instruction file helps. That note uses Claude Code, and the method carries over.
