Codex not reading AGENTS.md? Where it looks, and fixes

You wrote a rule in AGENTS.md, and Codex acts as if it never saw it. Before you rewrite the rule in capital letters, check whether Codex loaded the file at all. Codex decides which instruction files to read once, when it starts, and the rules for which files make the cut are stricter than most people expect.

We tested every case below with Codex CLI 0.164 in a small repository. Each folder's AGENTS.md held a different secret word, and we asked Codex which secret words were in its instructions. That trick is the quickest way to check your own setup too, so it comes first.

Check what Codex loaded#

Put a harmless marker in each instruction file, like The secret word for the repo root is APPLE., then ask from the folder you normally work in:

codex exec "Reply with only the secret words that appear in your instructions, comma separated, or NONE. Do not run any commands or read any files."

The answer lists exactly the files that reached Codex. Our test repository looked like this:

repo/
├── AGENTS.md                  APPLE
├── services/payments/
│   ├── AGENTS.md              BANANA
│   └── pay.py
└── web/
    └── CLAUDE.md              CHERRY

And this is what Codex reported:

Each row below the table is one of the reasons a rule goes missing.

1. A folder below where you started is never read#

Codex walks from the project root (the Git root) down to the folder you started in, and stops there. It does not look in folders below it. Started at repo/, Codex never saw BANANA in services/payments/AGENTS.md.

That holds even while Codex works in that folder. We started Codex at the root and told it to run cat services/payments/pay.py first. It read the file and still reported only APPLE. The payments rules never arrived.

This is the biggest difference from Claude Code, which loads a subfolder's CLAUDE.md the moment it reads a file in that folder. In Codex, a nested AGENTS.md only counts if you start Codex in that folder or below it.

Fix: start Codex where the work is (cd services/payments && codex, or codex --cd services/payments). If a rule must hold everywhere, put it in the root AGENTS.md.

2. Codex doesn't read CLAUDE.md#

Started in web/, Codex reported APPLE only: the CLAUDE.md there was ignored. Codex reads AGENTS.override.md and AGENTS.md, plus any names you add yourself. If your team keeps its rules in CLAUDE.md because Claude Code came first, Codex can't see them.

Fix: tell Codex to read the other name too. In ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md"]

We ran the same question with that setting (codex exec -c 'project_doc_fallback_filenames=["CLAUDE.md"]' …) and got APPLE, CHERRY. Codex reads at most one file per folder, in this order: AGENTS.override.md, AGENTS.md, then your fallback names. So a folder with both an AGENTS.md and a CLAUDE.md still gives Codex only the AGENTS.md.

The other way round works as well: keep one AGENTS.md and put the line @AGENTS.md in CLAUDE.md, so Claude Code loads the same rules. Then both agents follow one file.

3. An AGENTS.override.md wins#

We added services/payments/AGENTS.override.md with the word FIG and started Codex in that folder. It reported APPLE, FIG. BANANA was gone: in each folder, an override file replaces that folder's AGENTS.md completely.

The same goes for your Codex home folder. ~/.codex/AGENTS.override.md, if it exists and isn't empty, is used instead of ~/.codex/AGENTS.md, for every project. An override someone made "for a minute" and forgot is a common reason the wrong rules show up.

Fix: look for AGENTS.override.md in your folder, every folder above it up to the repository root, and ~/.codex/. Delete or rename the one you don't want.

4. The file is cut off at 32 KiB#

Codex stops adding instruction files once their combined size reaches 32 KiB. We wrote a 38 KB AGENTS.md with DELTA in the first line and ECHO in the last. Codex reported DELTA only. The end of the file, and everything after it, was silently dropped. There was no warning.

With the limit raised, Codex had both:

codex exec -c project_doc_max_bytes=65536 "Reply with only the secret words that appear in your instructions, comma separated, or NONE. Do not run any commands or read any files."

Fix: keep files short (your most important rules first), move folder-specific rules into that folder's own AGENTS.md, or raise the limit in ~/.codex/config.toml with project_doc_max_bytes = 65536. The limit counts all files together, including your global one in ~/.codex/.

5. No Git repository, no walk#

Codex finds the project root from Git. We copied the repository without its .git folder and started Codex in services/payments/. It reported BANANA only. With no root to start from, Codex reads the instruction file in the current folder and nothing above it.

Fix: run git init at the top of the project, or start Codex in the folder whose AGENTS.md you want.

6. You changed the file mid-session#

Codex builds its instruction list when a run starts, and in the interactive app, when a session starts. An edit to AGENTS.md during a session doesn't reach that session.

Fix: start a new session after changing the rules. There is no cache to clear; a fresh start reads the files again.

When the file did load#

If the secret-word check shows your file arrived and Codex still breaks the rule, the problem is the rule, not the loading. A few things help:

• Be specific. "Run npm test before you say you're done" beats "make sure things work".
• Remove rules that contradict each other, including ones between your global and project files. Files closer to your folder come later in the prompt and usually win.
• If something must happen every time, don't leave it to instructions at all. A Stop hook can make Codex run your tests before it says done.

Checklist#

1. Ask for the secret words to see which files loaded.
2. Start Codex in the folder whose AGENTS.md should apply, or move the rule up to the root.
3. CLAUDE.md only? Add it to project_doc_fallback_filenames, or put @AGENTS.md in CLAUDE.md and keep one file.
4. Look for a forgotten AGENTS.override.md, including in ~/.codex/.
5. Over 32 KiB in total? Split the file or raise project_doc_max_bytes.
6. Restart after editing the rules.

Where Joxo fits#

When teammates each run their own agent on one project, some use Codex and some Claude Code, and the rules have to reach all of them. Joxo keeps the team's rules in one list and gives each person's agent the rule that applies, whichever agent it is. A correction you make once reaches everyone's agents.

Frequently asked questions#

Where does Codex look for AGENTS.md?#

First in your Codex home folder (~/.codex/AGENTS.override.md, else ~/.codex/AGENTS.md). Then in every folder from the Git root down to the folder you started Codex in, one file per folder. Folders below the one you started in are not read.

Does Codex read CLAUDE.md?#

No, not by default. Add project_doc_fallback_filenames = ["CLAUDE.md"] to ~/.codex/config.toml, and Codex reads CLAUDE.md in any folder that has no AGENTS.md.

Is there a size limit for AGENTS.md in Codex?#

Yes. All instruction files together are capped at 32 KiB by default, and anything past the cap is dropped without a warning. Raise it with project_doc_max_bytes in ~/.codex/config.toml.

Do I need to restart Codex after editing AGENTS.md?#

Yes. Codex reads the files when a session starts, so a new session picks up the change.