skip to content

In a monorepo, how does Codex decide which AGENTS.md files a session started in services/payments loads, and in what order?

level: middleimportance: must knowfreq 14%

answer

  1. global, then project
  2. walk from root down to cwd
  3. one file per directory
  4. override before AGENTS.md
  5. 32 KiB budget

basics

~20 s

Codex reads one global file from CODEX_HOME, then walks from the project root down to services/payments, taking at most one file per directory: AGENTS.override.md, else AGENTS.md, else a fallback name. Root comes first, so deeper files win, within a 32 KiB budget.

solid answer

~40 s

Codex builds an instruction chain once per run. First the **global** file: in `CODEX_HOME` (`~/.codex` by default) it uses `AGENTS.override.md` if present and non-empty, else `AGENTS.md`. Then the **project** files: it finds the project root (the nearest parent holding a `project_root_markers` entry, `.git` by default) and walks from there down to the working directory, taking at most one file per directory, checking `AGENTS.override.md`, then `AGENTS.md`, then any `project_doc_fallback_filenames`. Files are concatenated root first, so `services/payments` guidance appears last and overrides broader rules. Project files share `project_doc_max_bytes`, 32 KiB by default; the file that crosses it is truncated and later ones are dropped. So put the stricter rules in `services/payments/AGENTS.override.md` or `AGENTS.md`, and start Codex in that directory: a session started at the root never reads them.

code

markdown · 7 lines
markdown
# services/payments/AGENTS.override.md

## Payments service rules

- Use `make test-payments` instead of `npm test`.
- Never change files under `migrations/` without asking first.
- Money amounts are integers in minor units; never use floats.

go deeper

for a junior

Recall the two places instructions live: the global file in ~/.codex and AGENTS.md files in the repository, and that the file nearest your working directory has the last word.

for a middle

Walk through the discovery steps: root markers, one file per directory, override before AGENTS.md before fallbacks, root-first concatenation and the 32 KiB budget.

for a senior

Diagnose missing guidance from the symptoms: a session started at the root, an override hiding its sibling, an empty override, or a root file eating the byte budget.

for a principal

Decide how a monorepo splits guidance between a short root file and per-service files, and who owns overrides, so no team's rules get truncated away.

## Two scopes: global and project Codex, OpenAI's coding agent, reads Markdown instruction files called **`AGENTS.md`** before it does any work. It assembles them into one **instruction chain** when a run starts: once per `codex exec` run, and once per launched session in the terminal UI. Editing a file mid-session therefore changes nothing until the next run. The chain has two scopes: - **Global scope** — your Codex home directory, `~/.codex` unless the `CODEX_HOME` environment variable points elsewhere. Codex reads `AGENTS.override.md` if it exists, otherwise `AGENTS.md`, and uses only the first non-empty file. The override is meant as a temporary replacement: delete it and the base file applies again. - **Project scope** — the files in the repository, collected by a directory walk. ## The walk from the project root For the project scope, the 0.159.3 source follows these steps: 1. **Find the project root** by walking up from the working directory until a directory contains one of the `project_root_markers` (default: `.git`). If no marker is found, only the working directory is checked. 2. **List every directory** from the root down to the working directory, inclusive. Codex never walks past the root, and never looks *below* the working directory. 3. **Pick at most one file per directory**, testing names in order: `AGENTS.override.md`, `AGENTS.md`, then each name in `project_doc_fallback_filenames`. 4. **Concatenate root first**, joining files with blank lines. Text closer to the working directory comes later, so it overrides earlier guidance. ## One file per directory | Files present in a directory | What Codex loads from it | |---|---| | only `AGENTS.md` | `AGENTS.md` | | `AGENTS.override.md` and `AGENTS.md` | only `AGENTS.override.md` | | only `TEAM_GUIDE.md`, listed as a fallback | `TEAM_GUIDE.md` | | a name not on the fallback list | nothing | The override does not *add* to its sibling; it *replaces* it. That is what the payments team wants when its rules must not be diluted by a broader file in the same folder. ## The size budget **`project_doc_max_bytes`** caps the bytes read from project files; the default is **32 KiB** (`32 * 1024` in the source). Files are read in walk order, so the budget is spent root first: - the file that crosses the cap is **truncated** at the remaining byte count, and Codex logs a warning; - every deeper file is **dropped**; - empty files are skipped and cost nothing. The consequence matters in a monorepo: a bloated root `AGENTS.md` can push out the most specific file, which is usually the one you care about. The documented fixes are to raise `project_doc_max_bytes` or to move guidance into nested directories. ## Where the payments rules go For a payments service that needs stricter rules than the rest of the repository: - write them in `services/payments/AGENTS.override.md` (or `AGENTS.md` if there is no sibling to suppress); - start Codex **from that directory**, or pass `--cd services/payments`, because a session whose working directory is the repository root stops its walk at the root; - keep the root file short so the budget reaches the deepest file. Expected load order for a session in `services/payments`: the global file, the repository root `AGENTS.md`, `services/AGENTS.md` if one exists, then the payments file last. ## Symptoms and their usual causes | Symptom | Usual cause | |---|---| | nested rules never apply | the session started above the folder that holds them | | a folder's `AGENTS.md` is ignored | an `AGENTS.override.md` beside it, possibly an empty one | | the deepest rules are cut off mid-sentence | the byte budget ran out on larger files nearer the root | | unexpected global rules appear | an `AGENTS.override.md` in `CODEX_HOME`, or a different `CODEX_HOME` | | a custom file name is ignored | it is missing from `project_doc_fallback_filenames`, or the entry contains a path separator | Fallback entries must be bare file names: the source ignores an entry such as `docs/GUIDE.md`, as well as `.` and `..`, before probing the filesystem. ## Checking what loaded - Ask a run to list its instruction sources: `codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."` - `codex debug prompt-input` (marked experimental) renders the exact model-visible input as JSON. - If wrong guidance appears, look for an `AGENTS.override.md` higher in the tree or under `CODEX_HOME`, and check `echo $CODEX_HOME` in case Codex is reading a different home than the one you edited.

  • A developer starts Codex at the repository root and the payments rules never apply. Why?
    Codex walks from the project root down to the working directory and stops there; it never reads files below the working directory. Started at the root, it reads only the global file and the root `AGENTS.md`. Start in `services/payments` or pass `--cd services/payments`, and restart after editing, because the chain is built once per run.
  • What happens when `services/payments` holds an empty `AGENTS.override.md` beside a real `AGENTS.md`?
    In the 0.159.3 source, each directory contributes the first candidate file that exists, and an empty file is then skipped. The empty override is chosen and skipped, so that directory contributes nothing and its `AGENTS.md` is never read. Delete the empty override.
  • Your repository already keeps its agent guidance in `TEAM_GUIDE.md`. How do you make Codex read it?
    Add `project_doc_fallback_filenames = ["TEAM_GUIDE.md"]` to `config.toml`. Codex then checks `AGENTS.override.md`, `AGENTS.md`, then `TEAM_GUIDE.md` in each directory. Entries containing a path separator are ignored, and the change applies from the next run.

  • Codex reads every AGENTS.md in the repository, including folders below the working directory
  • AGENTS.md and AGENTS.override.md in the same folder are both loaded and merged
  • The root AGENTS.md wins over nested files because it is loaded first
  • There is no size limit, so a long root AGENTS.md costs nothing
  • Editing AGENTS.md mid-session takes effect on the next prompt

Assumes Codex 0.159.3: discovery order, one file per directory and the 32 KiB project_doc_max_bytes default are read from that release's source.