Course · Codex · Rules (AGENTS.md)

How Codex discovers and layers AGENTS.md files

One file at the root of budgetcli now carries the three facts everyone who touches the repo needs, and you know exactly what it costs: 284 tokens, every session, no matter what that session is actually about. Fine for a fact everyone needs. Not fine for the two rules that don’t fit that description. “Always show me a diff and explain your reasoning before editing” is a personal habit - paste it into the shared file and every teammate who clones budgetcli pays rent on your working style. And the rule about how the CSV-import module handles each bank’s quirks only matters when Codex is actually working in that directory; load it into a session about the reports endpoint and you’re paying for a fact that session will never use. Both want a narrower lease than the root file offers. Codex gives you one, because it doesn’t read a single AGENTS.md - it assembles several, and where a fact lives decides how often you pay for it.

The discovery walk

When Codex starts in a directory, it builds the project brief by walking a defined path and reading every AGENTS.md it finds along the way. The walk goes from broadest scope to most specific:

Global      ~/.codex/AGENTS.md            (you, every project on this machine)
Project     <git root>/AGENTS.md          (the repo, shared via git)
            <git root>/src/AGENTS.md       ↓ intermediate directories, if present
Local       <cwd>/AGENTS.md               (the directory you launched Codex in)

It starts at your global file in ~/.codex/, then jumps to the git root of the project and walks down the directory tree toward your current working directory, picking up any AGENTS.md it passes. The personal-habit rule goes in ~/.codex/AGENTS.md - it follows you across every repo and never lands in anyone else’s checkout, so it never becomes anyone else’s rent. The CSV-import rule goes in src/budgetcli/importers/AGENTS.md - say a short paragraph of bank-quirk notes, on the order of 50 tokens by the same estimator - where it only enters context, and only gets paid for, when Codex is actually working in that corner of the tree.

The discovery runs once per run - in the TUI that’s typically once per launched session. The full mechanics are pinned in the official AGENTS.md guide.

They concatenate - they don’t fight

This is the part people get wrong, so be precise about it. These files do not override each other wholesale. Codex collects every AGENTS.md on the walk and concatenates them - root down to cwd - joining them with blank lines into one combined brief. Your global file and the project file and any subdirectory file are all present at once. None cancels another; scoping a rule narrower doesn’t remove it from context when it’s relevant, it just stops it from showing up when it isn’t.

Order is how conflicts resolve. Files closer to your working directory appear later in the concatenated text, and the closer file wins when two rules brush against the same topic - later guidance overrides earlier guidance. So a rule in src/budgetcli/importers/AGENTS.md takes precedence over the same-topic rule at the repo root, which in turn takes precedence over your global ~/.codex/AGENTS.md. Broadest is the default; most specific is the final word. Layering doesn’t fix a bad rule - it just decides which bad rule wins.

That gives you a clean layering for budgetcli:

Global (~/.codex/AGENTS.md) - your personal working style across all projects. “Explain your reasoning before editing.” Follows you, ships to no one, costs no one but you.
Project root (budgetcli/AGENTS.md) - the team-shared truth: integer cents, the category list, date handling. Committed to git so every clone gets it. This is where the bulk of your last lesson lives, and where its 284 tokens get spent on every session regardless of task.
Subdirectory (src/budgetcli/importers/AGENTS.md) - rules that only matter in one module: the per-bank CSV quirks. Cheap, because it only enters context when Codex works there.

AGENTS.override.md wins at its level

There’s one more file in the picture. At every level of the walk - global and each project directory - Codex checks for AGENTS.override.md before the plain AGENTS.md, and the override file takes precedence at that level. It’s the escape hatch for when you need to supersede a rule without editing the shared file everyone depends on.

Concretely: if budgetcli/AGENTS.md is the committed team file and you drop a budgetcli/AGENTS.override.md next to it, the override beats the base file at the project root. That’s the move when you want a local exception - say, temporarily loosening a convention while you experiment - without touching version-controlled guidance your teammates rely on. Same idea globally: ~/.codex/AGENTS.override.md wins over ~/.codex/AGENTS.md.

The AGENTS.md walk is one row of Codex’s wider file map. The same global-versus-project line runs through everything you’ll meet later in the course - config.toml and its profiles, agent definitions, hooks, the .agents/skills/ standard. Hold the whole layout once and the rest of the course has an address:

committedin git, shared with your teamgitignoredlocal only, never sharedauto-generatedwritten by the tool; do not hand-edit

your-project/

~ (home directory)

Select a file or folder

Every entry shows what the file does, when Codex reads it, whether it belongs in git, and a working example.

You now have the full map of how Codex assembles its rules: global to subdirectory, concatenated in order, closer-wins, override-on-top. Scoping a rule right controls what it costs. It says nothing about whether Codex actually does what the rule asks once it’s loaded - a well-scoped rule that’s too vague to act on still buys you nothing. That’s the next move: what separates a rule Codex follows from one it skims past.