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.

   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, 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.

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

   Copy
4. 04

   Claude Code: reads both, but CLAUDE.md is the one it is built around

   Claude Code v2.1.260 ships a string describing its own behaviour as hardcoding CLAUDE.md and AGENTS.md discovery, so an AGENTS.md repository is not invisible to it. But the weighting is not subtle: CLAUDE.md appears roughly two hundred times across the binary — its own commands, its onboarding flow, its memory tooling and its context-cost guidance are all built on it — while AGENTS.md appears a handful of times, mostly in the codebase-survey and config-import paths that look for whatever instruction files a repository already has. In practice: put your rules in AGENTS.md and Claude Code will read them; put them in CLAUDE.md and every other feature that touches project memory, from /init to /memory to per-directory scoping, works on them too.

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 a one-line CLAUDE.md that says "see AGENTS.md" costs nothing. 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 line is enough when AGENTS.md is the source of truth
   Project conventions live in AGENTS.md at the repository root. Read that file.

   Copy

Troubleshooting

I added AGENTS.md and nothing changed

Check the tool before the file. All three CLIs here read it, but a fourth tool may not — and 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. If you are on Claude Code, /memory lists the memory files actually in play, which is the fastest way to see whether the file was picked up at all.

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 will follow AGENTS.md while Claude Code has both in context — and whichever it weights, the outcome will not match. Make one file the source of truth and reduce the other to a pointer.

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, 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.