What goes in AGENTS.md
AGENTS.md calls itself “a README for agents”. A README is for people: what the project is and how to get started. AGENTS.md is for the agent: how to build and test, what the code style is, what not to touch, what a pull request should look like. It is plain Markdown with no required fields.
The format is not OpenAI’s alone. It sits under the Agentic AI Foundation at the Linux Foundation and is read by Codex, Cursor, GitHub Copilot coding agent, Gemini CLI, Google Jules, Aider, Devin, Windsurf, Zed, Warp, VS Code and JetBrains Junie, among others. According to agents.md, more than 60,000 open-source projects use it.
How Codex reads it, exactly
At the start of every session Codex builds an instruction chain in three steps.
- Global. In your Codex home directory (~/.codex, or the directory in CODEX_HOME), Codex reads AGENTS.override.md if it exists, otherwise AGENTS.md. Only the first non-empty file counts.
- Project. From the project root, usually the Git root, Codex walks down to the directory you are working in. In each directory it checks AGENTS.override.md, then AGENTS.md, then the names in
project_doc_fallback_filenames. It takes at most one file per directory. Without a project root, Codex checks only the current directory. - Merge. The files found are concatenated from the root down, separated by blank lines. A file closer to your working directory comes later and therefore wins on conflicting instructions. Empty files are skipped. Codex stops once the total reaches
project_doc_max_bytes, 32 KiB by default.
| Setting in ~/.codex/config.toml | What it does | Default |
|---|---|---|
project_doc_fallback_filenames |
Extra file names per directory, for example ["TEAM_GUIDE.md", ".agents.md"] |
None |
project_doc_max_bytes |
Cap on all instructions combined, for example 65536 |
32 KiB |
A change to the configuration or to an AGENTS.md needs a new session.
An example. You work in services/payments/ of this repo:
~/.codex/AGENTS.md personal preferences
repo/AGENTS.md conventions for the whole repo
repo/services/AGENTS.md conventions for all services
repo/services/payments/AGENTS.override.md temporary deviation
Codex then joins them in this order: the global file, repo/AGENTS.md, repo/services/AGENTS.md, and the AGENTS.override.md in payments. An AGENTS.md next to that override in the same directory is skipped. To see what actually loaded, ask Codex at the start of a session to list the instructions it received.
The misconception: everything in AGENTS.md gets through
Many teams keep adding to one large file and assume the agent reads all of it. Codex cuts the chain at 32 KiB, and what sits in the global and higher-level files comes before what sits deep in a subdirectory. A long global AGENTS.md can push a subdirectory’s instructions out of the window. Keep each file short and put specific rules in the directory where they apply; in a monorepo the nearest file wins. An explicit instruction in chat always overrides the file, according to agents.md.
AGENTS.md next to CLAUDE.md
From version 2.1.277, Claude Code reads AGENTS.md as project instructions when there is no CLAUDE.md or CLAUDE.local.md in the working directory or the directories above it; the Project instructions setting can change that. If your repo already has a CLAUDE.md, put an @AGENTS.md line at the top: Claude Code then loads the shared file and does not read it twice. The other way round, Codex can read an existing CLAUDE.md if you add that name to project_doc_fallback_filenames. A team running Codex and Claude Code side by side then keeps its conventions in one place.
What this means for a team
A committed AGENTS.md travels with the repo to everyone, alongside the README and other tracked documentation. Codex memories live on one machine, and OpenAI’s own advice is to keep required team guidance in AGENTS.md or checked-in documentation, not in memories. See Does Codex remember previous work?. But AGENTS.md is also manual work: someone has to write it, trim it and keep it current. It can hold decisions and point to other documents, but it does not fetch email or documents itself, and everything has to fit under the 32 KiB cap. How to capture that wider knowledge is in How to give AI agents your company context.
Where Bombos fits
AGENTS.md gives every agent the same rules for one repo; Bombos gives every AI tool on the team one shared memory above that. It keeps the team’s knowledge and the rules the team learns, and reads what already exists in email, documents and repos, so Codex, Claude Code or Cursor can look it up without it having to fit in a 32 KiB file. One developer can try it first for their own agents.
Related questions
What is the difference between AGENTS.md and AGENTS.override.md?
In the same directory AGENTS.override.md wins: if it exists, Codex skips the regular AGENTS.md there. Useful for a temporary or personal deviation without editing the shared file.
Does Claude Code read AGENTS.md?
Yes, from Claude Code v2.1.277, when there is no CLAUDE.md or CLAUDE.local.md in the working directory or the directories above it. If both exist, Claude Code reads only CLAUDE.md, unless it contains an @AGENTS.md import.
Can Codex read a file with another name, like CLAUDE.md?
Yes, through project_doc_fallback_filenames in ~/.codex/config.toml. Codex tries those names in each directory when there is no AGENTS.override.md or AGENTS.md.
Why doesn't Codex see my change to AGENTS.md?
Codex builds the instruction chain when a session starts. Start a new session after a change, and check that the total stays under project_doc_max_bytes.
