AGENTS.md: Project Context for Agents

Start with the mental model, because it makes everything else obvious: AGENTS.md is a README written for your coding agent instead of for a human.

A README.md tells a person how to get started — what the project is, how to install it, how to contribute. An AGENTS.md tells an agent the extra, often tedious context it needs to do real work in your repo: the exact build and test commands, the code-style rules you actually enforce, which directories are off-limits, how you like commits phrased. Splitting them keeps each file focused — humans don't wade through agent minutiae, and the agent gets a predictable, dedicated place to look.

Three things make AGENTS.md worth learning as a standard rather than a Codex quirk:

• It's plain Markdown with no required fields. There is no schema, no mandatory headings — Codex simply parses the text you write. Use whatever sections help.
• It's open and cross-tool. AGENTS.md is stewarded by the Agentic AI Foundation under the Linux Foundation and emerged from collaboration across OpenAI Codex, Google's Jules, Cursor, Amp, Factory and others. The same file is read by 30+ tools and used by 60,000+ open-source projects, so the context you write once is reused everywhere.
• It's the right home for durable guidance. The official advice is blunt: "A short, accurate AGENTS.md is more useful than a long file full of vague rules." Recommended (all optional) sections: project overview, build/test/lint commands, code style, testing, security considerations, and commit/PR guidelines.

Note the filename precisely: it is AGENTS.md, not CLAUDE.md. That's the convention Codex and the broader open standard use — a different agent, a different file.

Before Codex touches your repo, it reads a global instruction file from the Codex home directory — ~/.codex by default, or wherever $CODEX_HOME points. This is where your personal, every-project preferences live: "always run tests before claiming done," "prefer functional style," "never push without asking."

The rule at this level is simple and worth memorizing:

Codex reads ~/.codex/AGENTS.override.md if it exists; otherwise ~/.codex/AGENTS.md — and uses only the first non-empty file it finds.

So at the global scope there is exactly one file in play. The .override.md variant, if present, wins outright over the plain AGENTS.md at that same level — without you having to delete or edit the base file. That makes it ideal for temporary or machine-specific tweaks you don't want to commit into your real global file.

This global file is the weakest layer in the final merge: it sits earliest in the combined prompt, so any project guidance that follows can override it. Think of it as your defaults, not your laws.

After the global file, Codex builds the project layer by walking your directory tree. The direction matters and is the single most-confused part of the model, so go slow:

Starting at the project root (typically the Git root), Codex walks down to your current working directory. In each directory along that path, it picks at most one file, checking in order: AGENTS.override.md, then AGENTS.md, then any name in project_doc_fallback_filenames.

So if you launch Codex from repo/packages/api/, it considers AGENTS.md files at repo/, repo/packages/, and repo/packages/api/ — picking one file per directory, override first.

~/.codex/AGENTS.md            ← global  (weakest)
repo/AGENTS.md                ← project root
repo/packages/AGENTS.md       ← mid-level
repo/packages/api/AGENTS.md   ← deepest, closest to cwd  (strongest)

Within a directory, the lookup order is a fallback chain: an AGENTS.override.md beats a plain AGENTS.md, and only if neither exists does Codex reach for the alternate filenames you've registered in project_doc_fallback_filenames (more on that key below). It never loads two files from the same directory — first match wins, then it moves to the next directory down.

This is what the AGENTS.md spec means by nested files for monorepos: drop an AGENTS.md into each package, and every subproject ships tailored instructions that apply only when you're working inside it.

Now the payoff. Codex doesn't pick one file — it combines them. The merge rule is precise:

Codex concatenates the files from the root down, joining them with blank lines. Files closer to your current directory appear later in the combined prompt, and later text overrides earlier text on conflicts.

That's the whole algorithm. The ordering is global → root → ... → deepest, and because a model weights later instructions more heavily, the file nearest your work wins. Restating the precedence as a table:

At every level, the .override.md form takes precedence over plain AGENTS.md at that same level before this stacking even happens. The result is a clean cascade: write broad rules high up, then override narrowly where a subproject genuinely differs — exactly like CSS specificity or layered config files.

The practical instinct to build: don't repeat shared rules in every package. State them once at the root and only write a deeper file when a directory actually needs to change something.

Two keys in ~/.codex/config.toml shape how the project docs get loaded. You'll set them rarely, but knowing they exist prevents real confusion.

project_doc_max_bytes — the combined size cap. Codex injects your merged project docs on the first turn, and that injection has a byte budget — 32 KiB by default. As Codex walks root-down, it keeps adding files until the combined size hits the limit, then stops adding more (it skips empty files entirely along the way). Crucially this is a truncation/stop, not an error — but it means a bloated AGENTS.md high in the tree can crowd out the more specific guidance you actually wanted near your cwd. Another reason the official advice is short and accurate.

project_doc_fallback_filenames — alternate instruction filenames. If a directory has no AGENTS.md (and no override), Codex can treat other files as the instruction doc. Register them as an array:

# ~/.codex/config.toml
project_doc_max_bytes = 65536  # raise from the 32 KiB default
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

This is how teams that already maintain a TEAM_GUIDE.md or a dotfile-style .agents.md get Codex to honor it without renaming everything. The fallback only fires when no real AGENTS.md/AGENTS.override.md exists in that directory — it sits last in the per-directory lookup chain.

Because specific values and newer keys move, confirm details against the live discovery guide rather than trusting a number you read months ago.

One AGENTS.md section earns special treatment from Codex's GitHub integration: a heading named ## Review guidelines. When Codex reviews a pull request — triggered automatically, or manually by commenting @codex review on the PR — it reads the review guidelines from the closest AGENTS.md to each changed file and uses them to prioritize what to flag.

That "closest file per changed file" rule is the same nearest-wins cascade you just learned, applied per-file: a change in packages/api/ is reviewed against packages/api/AGENTS.md's guidelines if present, otherwise the nearest ancestor's. So you can give different parts of a monorepo different review priorities.

A minimal example:

## Review guidelines

- Flag any new SQL query that isn't parameterized.
- Require tests for every change under `src/billing/`.
- Block direct calls to the payments API outside `src/payments/`.
- Don't nitpick formatting — Prettier handles it.

Keep these focused on what matters for your codebase; Codex posts a standard GitHub-formatted review and, by design, surfaces only the higher-severity issues rather than drowning the PR in trivia. This turns AGENTS.md from passive context into an active policy that shapes both how Codex writes code and how it reviews it.

You don't have to write AGENTS.md from a blank page. Run the /init slash command inside Codex and it inspects the project and generates an AGENTS.md scaffold in the current directory — a sensible starting structure you then trim and correct.

Treat what /init produces as a draft, not gospel. The discipline that makes AGENTS.md actually help:

• Be short and accurate. A long file of vague aspirations ("write clean, maintainable code") wastes the byte budget and teaches the agent nothing. Concrete, checkable rules ("run pnpm test before finishing," "never edit generated/") earn their place.
• Show the commands. The single highest-value content is the exact build/test/lint commands. A common failure is making Codex guess them.
• Don't overload prompts with what belongs in AGENTS.md. Durable, every-session rules go in the file; one-off instructions go in your prompt. Repeating standing rules in every prompt is a smell.
• Layer instead of repeat. Shared rules at the root; deeper files only to override. Lean on the cascade you learned rather than copy-pasting.
• Remember there is no /undo. AGENTS.md changes are just file edits — version them with Git like any other source. Codex itself has no undo command; you roll back through Git.

The payoff compounds: a tight, layered AGENTS.md means every future session — and every other AGENTS.md-aware tool — starts already knowing your project, instead of you re-explaining it each time.