DownloadCodex Unofficial guide
English

Fix Codex not following your AGENTS.md

If Codex ignores AGENTS.md, check five things. Are you in the repository you think, and is the file non-empty? Is there an AGENTS.override.md higher up taking priority? Are custom filenames listed in project_doc_fallback_filenames? Are your files under the 32 KiB project_doc_max_bytes limit? And does CODEX_HOME point somewhere unexpected? Then restart Codex.

Applies to: Codex CLI, IDE extension, ChatGPT desktop app

Check what Codex actually loaded

codex --ask-for-approval never "Summarize the current instructions."

To see the exact files, write a log and read it:

codex -c log_dir=./.codex-log

Then check ./.codex-log/codex-tui.log.

Causes and fixes

SymptomLikely causeFix
Nothing loadsWrong folder, or the file is emptyRun codex status to confirm the workspace root. Add content to the file.
Wrong guidance appearsAn AGENTS.override.md higher in the tree or in ~/.codexRename or remove the override
Custom filename ignoredNot listed, or misspelled, in project_doc_fallback_filenamesFix the list in config.toml and restart
Instructions cut offCombined size passed project_doc_max_bytes (32 KiB default)Raise the limit or split into nested folders
Edits to the “right” file do nothingCODEX_HOME points elsewhereRun echo $CODEX_HOME before launching Codex

Stale instructions?

There’s no cache to clear. Codex rebuilds the instruction chain on every run and at the start of each TUI session. Restart Codex in the target folder.

Sources

We link to the official source for every instruction on this page. If anything here disagrees with them, trust the official source and tell us.

Read next