How to Write AGENTS.md for Codex

Who this is for and what you will get

If you keep repeating the same working rules in every repository, such as which tests to run, which package manager to use, or which dependencies need approval first, this guide is for you. By the end you will have a global AGENTS.md and a project-level one, you will know the order in which Codex reads them, and you will have a command that shows which files are active.^[1]

How Codex finds AGENTS.md files

Codex builds its instruction chain once per run, which in the terminal interface usually means once per session. The chain has two layers.^[1]

The global layer lives in the Codex home directory, ~/.codex by default, or in whatever directory the CODEX_HOME variable names. Codex looks for AGENTS.override.md there first and falls back to AGENTS.md. Only the first non-empty file is used.^[1]

The project layer starts at the project root, usually the Git root, and walks down to the current working directory. In each directory Codex checks AGENTS.override.md, then AGENTS.md, then any fallback names you configured, and it keeps at most one file per directory. If no project root can be found, only the current directory is checked.^[1]

Codex joins the files from the top down with blank lines. Files nearer the working directory appear later and win over earlier guidance. Empty files are skipped. Once the combined text reaches project_doc_max_bytes, which defaults to 32 KiB, no further files are added.^[1]

Step 1: write global defaults

Create the global directory and a file with preferences you want everywhere:

# ~/.codex/AGENTS.md

## Working agreements

- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.

To confirm the file loads, run this from any directory:

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

Codex should repeat the items from ~/.codex/AGENTS.md before it proposes any work.^[1] For a temporary global change, create ~/.codex/AGENTS.override.md and leave the base file alone. Delete the override to go back to the shared rules.^[1]

Step 2: add repository rules

In the repository root, add an AGENTS.md that covers the basic setup:

# AGENTS.md

## Repository expectations

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

Because Codex merges the global file with this one, you only need to write what is specific to the project.^[1]

Step 3: override rules in a subdirectory

When one team needs different commands, put an override in its folder. For the payments service, create services/payments/AGENTS.override.md:

# services/payments/AGENTS.override.md

## Payments service rules

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

In that directory the AGENTS.md beside the override is ignored, because the override takes its place.^[1] Start Codex from the payments directory to check the order:

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

The global file should come first, the repository root AGENTS.md second, and the payments override last.^[1] Codex stops searching when it reaches the current directory, so put each override as close as possible to the code it governs.^[1]

Adding code review rules

Codex's GitHub code review reads AGENTS.md as well. Add a ## Code Review Rules section to the file nearest the code a rule covers. Repository-wide checks go in the root file, and checks for one service go in a nested file.^[1]

Keep each rule short. State the behavior to flag, then give the safe alternative and any exception. Formatting and lint checks belong in CI rather than in review rules.^[1]

The sample rule in the official documentation is about experiments. It flags treatment comparisons filtered on what happened after users were exposed, such as conversion or retention. The safe path is to build cohorts from assignment or exposure and report conversion as an outcome.^[1]

Using a different filename

If a repository already has a file such as TEAM_GUIDE.md, list it in project_doc_fallback_filenames in ~/.codex/config.toml:

# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536

Restart Codex or start a new session so the change loads. Each directory is then checked in the order AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. Names outside that list are ignored for instruction discovery.^[1] The example raises the size limit to 65536 bytes so more guidance fits before truncation.^[1]

Switching profiles with CODEX_HOME

Setting CODEX_HOME points Codex at a different home directory. This is useful for a separate automation user that should follow its own rules:

CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"

The output lists files relative to that custom .codex directory. Run echo $CODEX_HOME before you launch Codex to see which home directory is active, since a value other than the default means you are reading a different set of files.^[1]

How to check which files loaded

Start Codex with codex -c log_dir=./.codex-log and read ./.codex-log/codex-tui.log to see which instruction files were used. If session logging is turned on, the newest session-*.jsonl file records the same information.^[1]

Common problems

• Nothing loads. Make sure you are in the repository you meant to use, that codex status shows the workspace root you expect, and that the instruction files are not empty.^[1]
• The wrong rules appear. Look for an AGENTS.override.md higher up the tree or under the Codex home directory. Rename or delete it to fall back to the normal file.^[1]
• Fallback names are ignored. Check the spelling in project_doc_fallback_filenames, then restart Codex.^[1]
• Instructions are cut off. Raise project_doc_max_bytes, or split large files across nested directories.^[1]
• Instructions look stale. Restart Codex in the target directory. Codex rebuilds the chain on every run and keeps no cache you need to clear.^[1]

Next steps

The official Codex documentation covers the remaining configuration options and the details of instruction discovery.^[1]