Skip to content

Writing repository rules for Codex with AGENTS.md

How Codex discovers instruction files across global, project and directory scope, what override files are for, what the 32 KiB limit means, writing code review rules, and diagnosing instructions that never load.

CurrentLast verified

Platforms

  • Codex CLI
  • ChatGPT desktop app (Codex)
  • Codex IDE extension

What the official documentation says

  • Codex reads AGENTS.md files before doing any work.

    Custom instructions with AGENTS.md

  • Codex builds an instruction chain when it starts — once per run, which in the TUI usually means once per launched session.

    Custom instructions with AGENTS.md

  • At global scope, Codex reads AGENTS.override.md in the Codex home directory (default ~/.codex unless CODEX_HOME is set) if it exists, otherwise AGENTS.md, and uses only the first non-empty file at that level.

    Custom instructions with AGENTS.md

  • At project scope, Codex walks from the project root (typically the Git root) down to the current working directory, checking AGENTS.override.md, then AGENTS.md, then any project_doc_fallback_filenames in each directory, including at most one file per directory.

    Custom instructions with AGENTS.md

  • Codex concatenates the files from the root down joined by blank lines, and files closer to the current directory override earlier guidance because they appear later in the combined prompt.

    Custom instructions with AGENTS.md

  • Codex skips empty files and stops adding files once the combined size reaches project_doc_max_bytes, which defaults to 32 KiB.

    Custom instructions with AGENTS.md

  • If Codex cannot find a project root, it only checks the current directory.

    Custom instructions with AGENTS.md

  • project_doc_fallback_filenames in ~/.codex/config.toml adds alternate instruction filenames and project_doc_max_bytes raises the limit; filenames not on that list are ignored for instruction discovery.

    Custom instructions with AGENTS.md

  • For Codex code review in GitHub, add a "## Code Review Rules" section to the AGENTS.md closest to the code the rules govern.

    Custom instructions with AGENTS.md

  • The documented rule-writing advice is to keep rules concise, explain the behavior to flag and any safe path or exception, and reserve formatting and lint checks for CI.

    Custom instructions with AGENTS.md

  • Setting the CODEX_HOME environment variable selects a different profile, such as a project-specific automation user.

    Custom instructions with AGENTS.md

  • Codex rebuilds the instruction chain on every run and at the start of each TUI session, so there is no cache to clear manually.

    Custom instructions with AGENTS.md

Why this is worth your time

The documented one-liner: Codex reads AGENTS.md files before doing any work. By layering global guidance with project-specific overrides, you start each task with consistent expectations, no matter which repository you open.

Put differently: this is not documentation. It is a precondition injected into every run. What you write here is far more reliable than whatever you paste at the top of each conversation.

Discovery order: three steps

Codex builds an instruction chain when it starts — once per run, which in the TUI usually means once per launched session.

Step one, global scope. In your Codex home directory (default ~/.codex, unless you set CODEX_HOME), Codex reads AGENTS.override.md if it exists, otherwise AGENTS.md. Only the first non-empty file at this level is used.

Step two, project scope. Starting at the project root — typically the Git root — Codex walks down to your current working directory. If it cannot find a project root, it only checks the current directory. In each directory along the path it checks AGENTS.override.md, then AGENTS.md, then any fallback names in project_doc_fallback_filenames. At most one file per directory is included.

Step three, merge order. Codex concatenates the files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt.

There is one capacity constraint: Codex skips empty files and stops adding files once the combined size reaches project_doc_max_bytes (32 KiB by default). When you hit the cap, raise the limit or split instructions across nested directories.

Global guidance

Create persistent defaults in your Codex home directory so every repository inherits your working agreements.

mkdir -p ~/.codex

Then write ~/.codex/AGENTS.md:

# ~/.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.

Confirm it loads:

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

Expected: Codex quotes the items from ~/.codex/AGENTS.md before proposing work.

When you need a temporary global override without deleting the base file, use ~/.codex/AGENTS.override.md. Remove the override to restore the shared guidance.

Layering project instructions

Repository-level files keep Codex aware of project norms while still inheriting your global defaults.

In the repository root:

# AGENTS.md

## Repository expectations

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

In a nested directory that needs different rules — say 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.

Verify by starting from that directory:

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

Expected: Codex reports the global file first, the repository root AGENTS.md second, and the payments override last.

The documentation gives one placement rule: Codex stops searching once it reaches your current directory, so place overrides as close to specialized work as possible.

Code review rules

For Codex code review in GitHub, add a ## Code Review Rules section to the AGENTS.md closest to the code the rules govern. Repository-wide checks go at the root; service-specific checks go in a nested file.

The documented example shows the shape of a good rule:

## Code Review Rules

### Experiment cohorts

- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
  Safe path: build cohorts from assignment or exposure; report conversion as an outcome.

Note it has two halves: the behavior to flag, plus a safe path. The stated writing advice is three points — keep rules concise, explain the behavior to flag and any safe path or exception, and reserve formatting and lint checks for CI.

That last one is worth heeding. Let review do the judgement a person would make; let CI do the checks a machine is better at.

Custom fallback filenames

If your repository already uses a different filename — TEAM_GUIDE.md, say — add it to the fallback list and Codex treats it like an instructions file.

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

Restart Codex or run a new command so the updated configuration loads.

Codex then checks each directory in this order: AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. Filenames not on this list are ignored for instruction discovery.

Incidentally, the project_doc_max_bytes = 65536 line above raises the cap from 32 KiB to 64 KiB, allowing more combined guidance before truncation.

Switching profiles with CODEX_HOME

To use a different profile — a project-specific automation user, for instance — set the CODEX_HOME environment variable:

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

Expected: the output lists files relative to the custom .codex directory.

Troubleshooting

Nothing loads. Verify you are in the intended repository and that codex status reports the workspace root you expect. Ensure instruction files contain content — Codex ignores empty files.

Wrong guidance appears. Look for an AGENTS.override.md higher in the directory tree or under your Codex home. Rename or remove it to fall back to the regular file.

Codex ignores fallback names. Confirm you listed the names in project_doc_fallback_filenames without typos, then restart Codex so the updated configuration takes effect.

Instructions truncated. Raise project_doc_max_bytes or split large files across nested directories to keep critical guidance intact.

Profile confusion. Run echo $CODEX_HOME before launching Codex. A non-default value points Codex at a different home directory than the one you edited.

Instructions look stale. Restart Codex in the target directory. The documentation is explicit: Codex rebuilds the instruction chain on every run (and at the start of each TUI session), so there is no cache to clear manually.

How to do it

  1. Create global defaults — ensure ~/.codex exists and add an AGENTS.md there with your reusable preferences.
  2. Add an AGENTS.md in the repository root covering that project's expectations.
  3. Add AGENTS.override.md in nested directories that need different rules, placing overrides as close to the specialized work as possible.
  4. For review rules, add a "## Code Review Rules" section to the AGENTS.md closest to the code they govern.
  5. If the repository already uses a different filename, add it to project_doc_fallback_filenames in ~/.codex/config.toml.
  6. Verify with: codex --ask-for-approval never "Summarize the current instructions." from a repository root, and confirm it echoes global and project guidance in precedence order.

On Windows

  1. Instruction discovery is platform-independent; on Windows the Codex home directory resolves to %USERPROFILE%\\.codex by default.
  2. If you run both the Windows ChatGPT desktop app and a Codex CLI inside WSL, they do not share a Codex home by default and therefore do not share a global AGENTS.md — see the Windows tutorial for how to reconcile that.

On mobile

N/AAGENTS.md files are repository and filesystem configuration, and the official page does not describe mobile behaviour. When driving a host from a phone through Remote, the instruction chain that applies is the host's.

Use cases

  • Making every repository inherit your personal working agreements, such as always running tests after JavaScript changes.
  • Giving a subdirectory such as a payments service its own rules.
  • Encoding the review points your team keeps repeating as Code Review Rules.
  • Using AGENTS.override.md for a temporary override you can delete to restore the shared guidance.

Common mistakes

  • Piling all guidance into one enormous root AGENTS.md. Codex stops adding files once the combined size reaches project_doc_max_bytes (32 KiB by default).
  • Using a repository's own filename such as TEAM_GUIDE.md without adding it to project_doc_fallback_filenames, then wondering why it is never read.
  • Keeping both AGENTS.override.md and AGENTS.md in one directory and expecting both to apply — Codex includes at most one file per directory, and the override wins.
  • Putting formatting and lint rules into Code Review Rules. The documented advice reserves those for CI.
  • Changing configuration without restarting Codex and expecting new fallback filenames to take effect.

FAQ

What is the exact discovery order?
Three steps. Global scope: in the Codex home directory (default ~/.codex unless CODEX_HOME is set), Codex reads AGENTS.override.md if it exists, otherwise AGENTS.md, using only the first non-empty file at that level. Project scope: starting at the project root (typically the Git root), Codex walks down to your current working directory, checking AGENTS.override.md, then AGENTS.md, then any fallback names in each directory, and including at most one file per directory. Merge order: files are concatenated from the root down and joined with blank lines, so files closer to your current directory override earlier guidance.
What are the override files for?
They let you replace guidance temporarily without deleting the base file. The documented use is ~/.codex/AGENTS.override.md for a temporary global override — remove the override to restore the shared guidance. The same applies per directory in a project — where an AGENTS.override.md exists, the AGENTS.md beside it is ignored.
What happens if the instructions get too long?
Codex skips empty files and stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default. The two documented remedies are raising the limit or splitting instructions across nested directories.
How should code review rules be written?
Add a "## Code Review Rules" section to the AGENTS.md closest to the code the rules govern — repository-wide checks at the root, service-specific checks in a nested file. The documented advice is to keep rules concise, explain the behavior to flag and any safe path or exception, and reserve formatting and lint checks for CI.
How do I confirm what actually loaded?
Several documented checks. Run codex --ask-for-approval never "Summarize the current instructions." from a repository root and Codex should echo guidance from global and project files in precedence order. Use codex --cd subdir --ask-for-approval never "Show which instruction files are active." to confirm nested overrides replace broader rules. To audit which files Codex loaded, opt into a plaintext TUI log with codex -c log_dir=./.codex-log and check ./.codex-log/codex-tui.log, or inspect the most recent session-*.jsonl file if session logging is enabled.

Official sources

These are the pages this tutorial is checked against. Follow them if you need the vendor's exact wording.

Source status