Codex reads AGENTS.md files before it does any work. It loads a personal file from ~/.codex, then every AGENTS.md from your project root down to the folder you started in, and joins them so the most specific instructions come last and win.
This guide covers exactly how that discovery works, the overrides and limits that trip people up, what to put in the file, and how to check what Codex actually loaded. It is based on OpenAI's Custom instructions with AGENTS.md page and related docs, read on 26 October 2026. For the open format itself and which other tools read it, see the general AGENTS.md guide.
How does Codex find and load AGENTS.md files?
Codex builds an "instruction chain" once per run. In the interactive CLI that usually means once per session you launch. It follows three steps:
- Global scope. In your Codex home folder (
~/.codex, or whereverCODEX_HOMEpoints), Codex readsAGENTS.override.mdif it exists, otherwiseAGENTS.md. Only the first non-empty file counts. - Project scope. Starting at the project root, Codex walks down to your current working directory. In each folder it checks
AGENTS.override.md, thenAGENTS.md, then any names inproject_doc_fallback_filenames, and includes at most one file per folder. If it cannot find a project root, it checks only the current folder. - Merge. Codex concatenates the files from the root down, separated by blank lines. Files closer to your current folder appear later in the prompt, so they override earlier guidance.
For a repo like this, started from services/payments/:
~/.codex/AGENTS.md 1. your personal defaults
repo/AGENTS.md 2. team rules for the whole repo
repo/services/payments/AGENTS.md 3. payments rules, read last
repo/services/search/AGENTS.md not loaded: not on the path
Two details matter in practice. First, Codex stops at your current folder; it does not read files in sibling or child folders. Start Codex where the work is, or use codex --cd services/payments. Second, the project root is the nearest folder containing .git by default. You can change that with project_root_markers in config.toml, for example [".git", ".hg", ".sl"], or set it to [] to treat the current folder as the root.
In the desktop app, Codex discovers AGENTS.md, skills and config.toml from a chat's primary folder only. Secondary folders you add are available for reading and editing, but their project files are not discovered automatically.
What does AGENTS.override.md do?
AGENTS.override.md replaces the regular file in the same folder. It does not add to it. OpenAI's example is a payments service whose AGENTS.override.md says to use make test-payments instead of npm test; the AGENTS.md next to it is ignored.
Use it in two situations:
- A temporary global change. Create
~/.codex/AGENTS.override.mdto change your personal defaults for a while, then delete it to go back. - A folder that needs different rules. Put an override in a subfolder when a team's rules conflict with the repo's, rather than piling exceptions into the root file.
Because an override silently hides the regular file, it is also the first thing to look for when Codex follows the wrong rules.
How big can AGENTS.md be in Codex?
Codex skips empty files and stops adding project files once their combined size reaches project_doc_max_bytes, which is 32 KiB (32,768 bytes) by default. The file that crosses the limit is cut off, and anything past it never reaches the model.
One wording difference to know about: OpenAI's advanced configuration page describes the setting as how much to read from each AGENTS.md file. The AGENTS.md guide describes a combined limit, and the loader in the Codex source at release 0.164.0 works that way: one byte budget shared by the project files from the root down. In that code, your global file in ~/.codex is loaded separately and does not count toward it.
You can raise it in ~/.codex/config.toml:
project_doc_max_bytes = 65536
The better fix is usually a shorter file. OpenAI's Codex best practices put it plainly: "A short, accurate AGENTS.md is more useful than a long file full of vague rules." If the file grows, keep the main one concise and point to task-specific Markdown files for planning, code review or architecture, or move rules into nested AGENTS.md files next to the code they govern.
How do you create an AGENTS.md with /init?
Run /init in the Codex CLI from the folder where you want the file. Codex generates an AGENTS.md scaffold in the current directory. The IDE extension and desktop app have the same /init command for the current project. The full list is in the Codex slash commands guide.
Treat the scaffold as a first draft. Edit it to match how your team really builds, tests, reviews and ships, then commit it so everyone, and every Codex session, gets the same rules.
For personal defaults, create ~/.codex/AGENTS.md by hand. OpenAI suggests using the global file for how Codex works with you (review style, verbosity, defaults) and keeping repo files for team and codebase rules.
What should a Codex AGENTS.md contain?
OpenAI's best practices list what a good file covers:
- Repo layout and important directories
- How to run the project
- Build, test and lint commands
- Engineering conventions and PR expectations
- Constraints and do-not rules
- What done means and how to verify work
Here is an example written for this guide that follows that list. Replace the commands with your own:
# AGENTS.md
## Layout
- apps/web: Next.js front end
- packages/api: REST API, the only code that talks to the database
## Commands
- Install: pnpm install
- Test: pnpm test
- Lint and types: pnpm lint && pnpm typecheck
## Conventions
- TypeScript strict mode. No `any` without a comment explaining why.
- Use pnpm, never npm or yarn.
## Do not
- Edit files under packages/api/generated.
- Add a production dependency without asking first.
## Done means
- Tests, lint and typecheck pass.
- Summarize what changed and anything you could not verify.
Grow the file from real friction. OpenAI's customization guide suggests adding a rule when Codex repeats a mistake, adding routing hints when it reads too many files, and codifying review feedback you have given more than once. You can also ask Codex to update AGENTS.md itself after you correct it, or comment @codex add this to AGENTS.md on a GitHub pull request.
Rules that must hold every time are better enforced by tools than by prose. OpenAI suggests pairing AGENTS.md with pre-commit hooks, linters and type checkers; Codex hooks are another option.
Can Codex use CLAUDE.md or another filename?
Yes, through fallback filenames. If your repo already has instructions under another name, list it in config.toml:
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
Codex then checks each folder in this order: AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. A fallback is used only when the names before it are missing in that folder, and names not on the list are ignored. Restart Codex after editing so the new config loads.
The same mechanism works for a CLAUDE.md if you want Codex to read it in folders that have no AGENTS.md. If you are moving from Claude Code or Cursor, the CLI's /import command migrates instruction files into AGENTS.md, along with settings, skills and hooks. For keeping both tools happy from one file, see CLAUDE.md vs AGENTS.md.
How do you check which instructions Codex loaded?
OpenAI documents these checks:
# from the repo root: Codex should echo your global and project rules in order
codex --ask-for-approval never "Summarize the current instructions."
# from a subfolder: confirm nested files and overrides apply
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."
# write a plaintext TUI log you can search
codex -c log_dir=./.codex-log
The last one writes ./.codex-log/codex-tui.log. For an exact answer, codex debug prompt-input prints the model-visible prompt input as JSON, which the CLI reference recommends for "debugging instruction discovery."
There is no cache to clear. Codex rebuilds the chain at the start of every run, so if instructions look stale, restart Codex in the right folder.
Why is Codex ignoring my AGENTS.md?
Work through these in order:
| Symptom | Likely cause and fix |
|---|---|
| Nothing loads | You started Codex outside the repo, or the file is empty. Run /status to check the writable roots and add content |
| A subfolder's rules are missing | Codex only reads folders between the project root and your current folder. Start Codex in that subfolder |
| The wrong rules apply | An AGENTS.override.md higher up the tree or in ~/.codex is hiding the regular file. Rename or remove it |
| Your global file is ignored | CODEX_HOME points to a different folder. Run echo $CODEX_HOME before launching |
| A fallback name is ignored | A typo in project_doc_fallback_filenames, or Codex was not restarted after the edit |
| Late rules have no effect | The combined files passed project_doc_max_bytes. Shorten them or raise the limit |
| Edits do not show up | Codex reads the chain once per session. Start a new session |
If you use the desktop app with several folders, also check that the repo is the chat's primary folder.
Does AGENTS.md work in code review, the cloud and subagents?
Yes, in each of these:
- Code review on GitHub. Codex searches the repo for
AGENTS.mdfiles and follows## Code Review Rulessections, applying the root file and any more specific file that covers each changed file. OpenAI's GitHub review docs suggest starting with two or three concise rules and leaving formatting and lint checks to CI. - Codex cloud. OpenAI's cloud docs say that if your repo includes
AGENTS.md, the agent uses it to find project-specific lint and test commands. See the Codex cloud guide. - Subagents. Local Codex delegates to subagents when you ask directly or when applicable
AGENTS.mdor skill instructions request it. More in the Codex subagents guide.
How is AGENTS.md different from skills, config.toml and memories?
| Layer | Use it for | Loaded |
|---|---|---|
AGENTS.md |
Rules for every task in a repo: commands, conventions, limits | Always, at the start of each run |
Skills (SKILL.md) |
Step-by-step workflows such as a release or a review routine | Only when invoked or matched by description |
config.toml |
Model, sandbox, approvals, MCP servers | Settings, not instructions |
| Memories | Context Codex learned from earlier work | A recall layer; OpenAI says it should not be the only source for rules that must always apply |
A simple way to decide: a rule Codex should follow on every task, such as running the linter before a PR, belongs in AGENTS.md; a procedure it needs only for one kind of task, such as your release checklist, is a skill. The Codex skills guide covers skill folders and the Codex config guide covers config.toml.
Where should your Codex skills live?
AGENTS.md travels with each repo, but your skills often outgrow any single project. Kipt keeps your prompts and Agent Skills as Markdown in a private GitHub repo you own, and installs every skill into Codex or Claude Code with npx skills add https://github.com/<you>/<repo>.git --all -g. To turn a procedure from your AGENTS.md into a skill, the free SKILL.md generator builds one in the browser.