Codex AGENTS.md: global, project and override instruction files explained

• Global: your Codex home, which is ~/.codex by default or the folder in CODEX_HOME if set. Codex reads AGENTS.override.md if present, otherwise AGENTS.md, and uses only the first non-empty file.
• Project: Codex walks from the project root (usually the Git root) down to the current directory. If it finds no root, it checks only the current directory.
• Each directory gives at most one file, checked in this order: AGENTS.override.md, AGENTS.md, then any names in project_doc_fallback_filenames.
• Files are joined from the root down, separated by blank lines. Later files, closer to your current directory, override earlier guidance.

Use the global file for personal habits that apply to every repository, such as your preferred package manager or test command.

mkdir -p ~/.codex

# Personal defaults

- Run npm test after changing JavaScript files.
- Prefer pnpm when installing dependencies.
- Ask before adding production dependencies.

Put shared team rules in AGENTS.md at the repository root. For a folder that needs different rules, add an AGENTS.override.md inside it.

# Repository rules

- Run npm run lint before opening a pull request.
- Document public utilities in docs/ when behavior changes.

# Payments service rules

- Use make test-payments instead of npm test.
- Never rotate API keys without notifying the security channel.

Loading stops once the combined size reaches project_doc_max_bytes, which defaults to 32 KiB. Empty files are skipped. You can also tell Codex to treat other file names as instruction files with project_doc_fallback_filenames.

project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

After changing these settings, restart Codex or run a new command. Codex builds the instruction chain when it starts: once per run, and in the TUI usually once per launched session.

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

codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."

• Nothing loads: confirm you are in the right repository and that the files are not empty.
• Wrong guidance: look for an AGENTS.override.md higher in the tree or in your Codex home.
• Instructions cut off: raise project_doc_max_bytes or split rules across nested folders.
• Unexpected home folder: run echo $CODEX_HOME to see which one is in use.