AGENTS.md is a file that tells a coding agent about your project. In Codex, typing /init creates an AGENTS.md scaffold for the current project. This guide covers what to fill in after the scaffold exists, the order Codex reads files, and how to split instructions so you stay under the size limit.
What AGENTS.md and /init do
AGENTS.md is an open format that the agents.md site describes as a "README for agents." It holds content that would clutter a human-facing README, such as build commands, how to run tests, and code style rules, written separately for agents. There are no required fields.
The Codex slash commands doc describes /init as creating "an AGENTS.md scaffold for the current project." That doc does not say exactly what goes into the scaffold. So always open the generated file yourself and check that it matches your actual project.
Items agents.md lists as common are the project overview, build and test commands, code style, testing instructions, and security considerations. Some people also include commit and PR rules and deployment steps.
The order Codex reads files
According to the Codex docs, the instruction list is built once when a run starts. If you edit a file, the change applies from the next run, and there is no cache to clear.
It looks at the global scope first. In the Codex home directory (default ~/.codex, which you can change with CODEX_HOME), it looks for AGENTS.override.md first and uses AGENTS.md if that is missing. At this step it uses only the first non-empty file.
Next is the project scope. Starting at the project root (usually the Git root) and walking down to the current working directory, it checks each directory for AGENTS.override.md, AGENTS.md, and then the names listed in project_doc_fallback_filenames, in that order. It reads at most one file per directory. If it cannot find a project root, it checks only the current directory.
The files it finds are concatenated from the root downward with a blank line between them. Files in closer folders come later, so they effectively take priority over earlier content.
- If AGENTS.override.md exists in the same folder, that folder's AGENTS.md is ignored.
- The default limit on the combined size (project_doc_max_bytes) is 32 KiB. Once it reaches the limit, no further files are added.
- If you hit the limit, raise the value (the docs example is 65536) or split the instructions into subfolders.
- To use a name other than AGENTS.md (for example TEAM_GUIDE.md), list it in project_doc_fallback_filenames in ~/.codex/config.toml and restart Codex.
The order I actually use
1) Run Codex in the project folder and type /init. 2) Open the generated AGENTS.md and fix anything wrong. 3) Write down specifically the parts the agent often gets wrong, content it cannot know unless a person tells it, such as "run tests with this command." 4) If the rules differ in a subfolder, put a separate file in that folder.
You can confirm the files were read using a method from the docs. The command below asks Codex to list the instruction sources it loaded. If they come out in the order of global file, root file, subfolder file, it is working.
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."
How it differs from other settings
It plays a different role from Codex's memory feature. The official docs describe memory as an aid for recall and say to put team rules that must be followed in AGENTS.md or documents checked into the repository. Memory is off by default and has to be turned on separately, so do not make it the only place your rules live.
The docs say personal "custom instructions" in Codex are stored in the global AGENTS.md (~/.codex/AGENTS.md). Put personal preferences in the global file and project rules in the repository file.
Instruction file names differ between tools. agents.md describes renaming an existing agent file to AGENTS.md and leaving a symlink under the old name. It also says some tools, such as Aider and Gemini CLI, need configuration before they read AGENTS.md. Check each tool's docs to see whether it reads this file. This guide is about Codex.
Real examples
A monorepo where only the payments service has a different test command.
In the root AGENTS.md I wrote "Run npm run lint before a PR," and in services/payments/AGENTS.override.md I wrote "Use make test-payments instead of npm test."
When working in the payments folder, both files are read, and the closer override file comes later. In other folders, only the root rules apply. You can see the order they were read with the check command above. This example follows the one in the official Codex docs.
Using Codex on a new project for the first time.
Type /init, then open the generated AGENTS.md and edit in the build and test commands and the folders to ignore yourself
A scaffold appears, and the parts you filled in become Codex's instructions from the next run. After that you do not have to type the same explanation every time. The scaffold's exact contents may vary by version, so check it.
Common mistakes and when not to use it
- Do not leave the scaffold /init generates without reviewing it. It may contain commands that do not fit your project.
- A long file can hit the 32 KiB limit, and files that come later may not be read. Do not pack everything into one file. Split by folder.
- If you create AGENTS.override.md in the same folder, AGENTS.md is ignored. It is easy to forget to delete an override file you made temporarily.
- Do not write passwords, tokens, or personal information in AGENTS.md. If it goes into the repository, it is exposed as is.
- After you rename a file or add a fallback name, you need to restart Codex.
FAQ
Does editing AGENTS.md apply immediately?
It is read once when a run starts, so it applies from the next run. The docs say there is no cache to clear.
How many AGENTS.md files can I have?
One per folder. At most one file is read per folder, and the combined size is capped at 32 KiB by default.
Does /init always create the same content?
The docs only say it "creates a scaffold." I could not confirm the specific contents, so look at the generated file yourself.
Checked against the official docs on 2026-10-30. Sources: Codex: how AGENTS.md loads instructions, Codex slash commands (/init), Codex memories, ChatGPT personalization (Codex custom instructions), AGENTS.md official site. How we write