skip to content

Codex

OpenAI's coding agent in the terminal, IDE, desktop app and cloud: layered AGENTS.md files, sandbox modes with approval policies, and codex exec for scripts. Interviewers pit it against Claude Code.

part ofAI coding toolsread it →
on this pageshow

explore

questions

6

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.

open as a page

What does Codex's `codex exec` command do, and what must you add before it may edit files in your repository?

level: juniorimportance: should knowfreq 12%

basics

~20 s

codex exec runs one Codex task without the interactive terminal UI, streaming progress to stderr and printing only the final message to stdout. It starts in a read-only sandbox, so it edits nothing until you pass --sandbox workspace-write.

open as a page

In Codex, what does sandbox_mode control versus approval_policy, and what does the default workspace-write plus on-request pairing allow without asking?

level: middleimportance: should knowfreq 10%

basics

~20 s

sandbox_mode sets what model-run commands can technically touch; approval_policy sets when Codex stops to ask. With workspace-write and on-request, Codex reads, edits and runs commands in the workspace freely, but asks before writing outside it or using the network.

open as a page

A CI job runs Codex's codex exec to fix failing tests unattended, and every command that downloads a dependency fails. Why, and how should the job be configured?

level: seniorimportance: should knowfreq 7%

basics

~20 s

By default codex exec never asks for approval, and its workspace-write sandbox keeps network access off, so downloads fail back to the model. Install dependencies before Codex runs, enable sandbox_workspace_write.network_access only if needed, and reserve --yolo for an isolated runner.

open as a page

How do you start a Codex Cloud task from the terminal, and how does its change reach your local checkout or a pull request?

level: middleimportance: nice to knowfreq 5%

basics

~20 s

codex cloud exec --env ENV_ID "task" submits a task to a published Codex Cloud environment; codex cloud is marked experimental in 0.159.3. Review the result in ChatGPT and commit or open a pull request there, or bring the diff home with codex apply TASK_ID.

open as a page

After upgrading to Codex 0.159.3, it refuses to start because config.toml sets approval_policy = "untrusted" — why, and what replaces that setting?

level: seniorimportance: nice to knowfreq 3%

basics

~20 s

Codex 0.159.3 no longer accepts approval_policy = "untrusted" and stops with an error until it is removed. Use read-only with on-request for cautious work, or mark the project trust_level = "untrusted" in ~/.codex/config.toml to keep command approvals strict.

open as a page