AGENTS.md: Which Coding CLIs Actually Read It

Steps

1. 01

   What AGENTS.md is trying to be

   AGENTS.md is a plain Markdown file at the root of a repository that carries the context a coding agent needs and a README does not: how to run the build, which commands verify a change, the conventions that are not obvious from the code. The pitch is that it is tool-neutral — one file, read by whichever agent a developer happens to use, instead of a different proprietary file per vendor. OpenCode states the rationale in its own shipped prompt text: README.md files are for humans, and AGENTS.md complements them with the detailed context coding agents need. The interesting question is how much of that neutrality is real, which is the rest of this page.

2. 02

   Codex CLI: AGENTS.md is the native format, with real precedence rules

   Codex does not merely tolerate AGENTS.md — its behaviour around the file is spelled out inside its own system prompt, which is about as first-class as support gets. Four rules ship in the v0.153.2 binary. The scope of an AGENTS.md file is the entire directory tree rooted at the folder containing it. More deeply nested AGENTS.md files take precedence when instructions conflict. For every file in a patch, the agent must obey any AGENTS.md whose scope covers that file. And direct system, developer or user instructions take precedence over AGENTS.md. There is also a practical note worth knowing: the AGENTS.md at the repository root and in directories from the working directory up to the root are already included with the developer message, so Codex does not re-read them — but when it works in a subdirectory or outside the working directory it checks for additional applicable files. OpenAI's Codex docs (checked 2026-10-01) add two limits: an AGENTS.override.md in the same directory is read before AGENTS.md, and Codex stops adding instruction files once they total 32 KiB by default (project_doc_max_bytes). CLAUDE.md is not on its default list, though you can add other file names with project_doc_fallback_filenames.

   repo/AGENTS.md                 # applies to the whole tree
   repo/packages/api/AGENTS.md    # wins inside packages/api on conflict
   repo/packages/web/AGENTS.md    # wins inside packages/web on conflict

   Copy
3. 03

   OpenCode: AGENTS.md out of the box, CLAUDE.md as a fallback, and the list is configurable

   OpenCode reads AGENTS.md out of the box and treats it as one entry in a list you control. Its own shipped config reference shows "instructions": ["AGENTS.md", "docs/style.md"] — AGENTS.md is the file the config documents first, and the mechanism is general, so you can point OpenCode at additional files without renaming anything. Its shipped prompt text tells the agent that files named AGENTS.md usually carry the project’s background, structure, coding styles and preferences and should be used to understand the project, that it should look at AGENTS.md files in subdirectories for more detail about specific parts, and that if it changes anything an AGENTS.md describes it must update that file to keep it current. One thing our strings pass missed, and OpenCode's rules docs state plainly (checked 2026-10-01): for Claude Code compatibility, a project CLAUDE.md is used when no AGENTS.md exists, and ~/.claude/CLAUDE.md when there is no global ~/.config/opencode/AGENTS.md. OPENCODE_DISABLE_CLAUDE_CODE=1 turns that off.

   // opencode.json
   {
     "instructions": ["AGENTS.md", "docs/style.md"]
   }

   Copy
4. 04

   Claude Code: reads AGENTS.md since v2.1.277 — but by default not when a CLAUDE.md exists

   Correction (2026-10-01): our 4 September reading of the v2.1.260 binary said Claude Code reads both files. Anthropic's memory docs, checked on 2026-10-01, say reading AGENTS.md directly requires Claude Code v2.1.277 or later — so v2.1.260 did not, and most of the AGENTS.md mentions we counted sit in its survey and config-import paths. The current default rule is simple: if there is an AGENTS.md and no CLAUDE.md or CLAUDE.local.md in your working directory or above it, Claude reads the AGENTS.md; if both exist, it reads your CLAUDE.md files only. You can change that in /config under Project instructions (claude-md-and-agents-md reads both), or keep a CLAUDE.md whose first line is @AGENTS.md, which imports the file. CLAUDE.md is still the file Claude Code is built around: /init, /memory and per-directory scoping all work on it.

5. 05

   What to actually do when a repository has both

   Pick one as the source of truth and make the other a pointer, rather than maintaining two files that drift. If your team is mostly on Codex or OpenCode, AGENTS.md is the natural home — and if you also keep a CLAUDE.md, make it import the file with @AGENTS.md. Anthropic's docs warn that a CLAUDE.md which only tells Claude in words to read AGENTS.md means Claude sees AGENTS.md only if it decides to open it. If your team is mostly on Claude Code, the reverse. What you should not do is duplicate the content: both files are resident in context for the tools that read them, so two copies of the same rules is double the cost per turn and guarantees that one of them will eventually be wrong. Codex ships an explicit precedence rule for nested AGENTS.md files, but no rule about AGENTS.md versus CLAUDE.md, because that is not a conflict the format anticipates.

   # CLAUDE.md — one import line is enough when AGENTS.md is the source of truth
   @AGENTS.md
   
   ## Claude Code only
   (add Claude-specific rules here, or nothing)

   Copy

Troubleshooting

I added AGENTS.md and nothing changed

Check the tool before the file. On Claude Code, three things stop AGENTS.md from loading (Anthropic's docs, checked 2026-10-01): a version older than v2.1.277, a CLAUDE.md or CLAUDE.local.md anywhere from your working directory up, or Project instructions set to claude-md in /config. /memory lists the files actually in play. Inside a monorepo, placement matters as much as content: Codex scopes an AGENTS.md to the directory tree beneath it, so a file in packages/api will not affect work at the repository root.

Different agents behave differently in the same repository

That is usually two files disagreeing rather than two tools disagreeing. If AGENTS.md and CLAUDE.md both exist and have drifted, Codex and OpenCode follow AGENTS.md while Claude Code, by default, reads only the CLAUDE.md — so the agents are working from different rules. Make one file the source of truth and turn the other into an @AGENTS.md import.

My AGENTS.md is long and the agent still misses things

Length is the problem, not emphasis. Instruction files are resident in context on every turn (and Codex stops adding them after 32 KiB by default), so anything an agent could work out for itself — the directory layout, what the package scripts do, generic advice like "write tests" — competes with the handful of lines that carry real information. OpenCode’s own guidance is that good AGENTS.md content is hard-earned context that took reading several files to infer. If a line is not that, delete it.

Nested AGENTS.md files are conflicting with the root one

Under Codex that is defined behaviour, not a bug: more deeply nested files take precedence on conflict, and each file governs its own subtree. Use it deliberately — put universal rules at the root and only the genuinely package-specific ones deeper. If you want a nested file to add rather than override, phrase it as an addition instead of restating the root rule with a different value.