Tool support, verified per vendor
Which AI coding tools read AGENTS.md?
14 of the 15 tools below read AGENTS.md as shipped, with nothing to configure. The two exceptions are the ones worth knowing before you write the file. Gemini CLI ignores it until you add context.fileName to your settings.json — its own default is GEMINI.md. And Claude Code reads it only in a project with no CLAUDE.md; where both exist, the AGENTS.md file does nothing.
Tool by tool
Every row read at an address the vendor publishes. The quote is theirs, not ours.
| Tool | Reads AGENTS.md | What the vendor says | Source |
|---|---|---|---|
| Claude CodeAnthropic | As shippedOnly when the project has no CLAUDE.md. Not yet available on Bedrock, Vertex or Foundry. | “in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under 'Project instructions' in /config” | code.claude.com |
| OpenAI CodexOpenAI | As shippedThe repo's page forwards to developers.openai.com, which did not answer; the filename and heading are the reading. | “# AGENTS.md — For information about AGENTS.md, see this documentation” | github.com |
| CursorAnysphere | As shipped | “If you prefer plain markdown, use AGENTS.md instead” | cursor.com |
| GitHub CopilotGitHub | As shipped | “These are specified in files called AGENTS.md, CLAUDE.md” | docs.github.com |
| Gemini CLIGoogle | Only if configuredSet `"context": { "fileName": ["AGENTS.md", "GEMINI.md"] }` in settings.json. Untouched, Gemini CLI ignores AGENTS.md. | “While `GEMINI.md` is the default filename, you can configure this in your `settings.json` file. To specify a different name or a list of names, use the `context.fileName` property” | github.com |
| AmpSourcegraph | As shippedAmp moved to this filename from its own AGENT.md, announced 20 August 2025. | “AGENTS.md: Give Amp durable guidance for your codebase.” | ampcode.com |
| DevinCognition | As shipped | “Add AGENTS.md files to provide context and instructions for Devin” | docs.devin.ai |
| Factory (Droid)Factory | As shipped | “Give Droid durable project instructions, commands, and guardrails with AGENTS.md” | docs.factory.ai |
| JulesGoogle | As shipped | “Jules now automatically looks for a file named AGENTS.md in the root of your repository” | jules.google |
| Kilo CodeKilo | As shippedAlso read from a global ~/.config/kilo/AGENTS.md and from any subdirectory of the project. | “AGENTS.md — The primary instruction file for Kilo” | kilocode.ai |
| OpenCodeSST | As shipped | “You can provide custom instructions to opencode by creating an AGENTS.md file” | opencode.ai |
| Roo CodeRoo Code | As shippedOn by default (useAgentRules), and can be switched off. Where both exist, AGENTS.md wins. | “Roo Code also supports loading rules from an AGENTS.md” | docs.roocode.com |
| WarpWarp | As shippedA pre-existing WARP.md still works, and Warp says it can be renamed to AGENTS.md at any time. | “Warp uses `AGENTS.md` as the default project rules file” | docs.warp.dev |
| WindsurfCognition | As shippedWindsurf is now a Cognition product alongside Devin; the two documentation sets are separate. | “Create AGENTS.md files to provide directory-scoped instructions to Cascade” | docs.windsurf.com |
| ZedZed Industries | As shippedZed also writes to the global AGENTS.md, not only reads it. | “Default Rules are appended to your global `AGENTS.md` file (`~/.config/zed/AGENTS.md` on macOS and Linux)” | github.com |
Where the format’s own list and the vendors disagree
The agents.md site names 16 supporting tools. That list is a useful starting point and it is not the same thing as asking each vendor. On 2026-09-19 it differed from the documentation in three ways:
- A tool that supports it is missing. Claude Code added AGENTS.md support on 18 September 2026 and is not on the list.
- Support is not one state. Gemini CLI is listed alongside tools that read the file as shipped, but it reads
GEMINI.mdby default and finds AGENTS.md only once you name it insettings.json. - Aider is listed, and its own docs do not mention the file. We asked 4 pages it publishes, including the one describing how it takes project conventions, and none names AGENTS.md. That is what we found rather than a statement from Aider — if it has said so somewhere we did not ask, this row is the thing that is wrong.
Not checked either way: Phoenix. The documentation would not load for us, which is a fact about our attempt and not about the tool, so it gets no row above in either direction.
If you already have a tool-specific file
Four of these tools shipped their own filename before the shared one, and in every case the old file is still live — it still works, still wins, or is still the default. Adding an AGENTS.md beside it does not automatically retire it.
| Tool | Its own file | What happens if you have both |
|---|---|---|
| Claude Code | CLAUDE.md | Only when the project has no CLAUDE.md. Not yet available on Bedrock, Vertex or Foundry. |
| Warp | WARP.md | A pre-existing WARP.md still works, and Warp says it can be renamed to AGENTS.md at any time. |
| Amp | AGENT.md | Amp moved to this filename from its own AGENT.md, announced 20 August 2025. |
| Gemini CLI | GEMINI.md | Set `"context": { "fileName": ["AGENTS.md", "GEMINI.md"] }` in settings.json. Untouched, Gemini CLI ignores AGENTS.md. |
One spelling trap sits underneath this. The shared filename is plural, and Amp’s own earlier file was the singular AGENT.md — it renamed to the plural in August 2025. If you have an AGENT.md file in a repository, it is the older singular name and most of the tools above will walk straight past it.
If you are writing one today
Put AGENTS.md in the repository root and write it for a competent new contributor: the commands that build and test, the conventions a newcomer would break, and the things in the tree that are not what they look like. Three details from the table are worth acting on. If your repository already has a CLAUDE.md, anyone on Claude Code will keep reading that and never see the new file. If anyone on the team uses Gemini CLI, they need "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } in their settings. And several tools — Kilo Code and Windsurf among them — also read an AGENTS.md placed in a subdirectory, so a monorepo can carry one per package rather than one overloaded file at the root.
Questions
What is AGENTS.md?
It is a plain Markdown file in the root of a repository holding the instructions you would otherwise repeat to an AI coding tool every session: how to run the tests, which package manager to use, what not to touch. The point of the shared filename is that one file serves whichever tool a contributor happens to use, instead of a separate CLAUDE.md, GEMINI.md and WARP.md sitting beside each other doing the same job.
Do all AI coding tools read AGENTS.md?
Not on the same terms. Of the tools checked here, 14 read it exactly as shipped with nothing to configure. Gemini CLI does not: its default filename is GEMINI.md, and it only looks for AGENTS.md once you add a context.fileName entry to settings.json. Aider, which the standard lists as supporting the format, does not mention AGENTS.md anywhere across four of its own documentation pages, including the conventions page that describes this exact feature.
Does Claude Code read AGENTS.md?
Yes, but conditionally, and this is the condition most likely to waste your time: Claude Code reads AGENTS.md only in a project that has no CLAUDE.md. If both files are present, CLAUDE.md wins and the AGENTS.md file does nothing at all. Support arrived on 18 September 2026, and is not yet available when running Claude Code through Bedrock, Vertex or Foundry.
Can I use one AGENTS.md across a whole team using different tools?
Largely yes, and that is the case for writing one. The practical exceptions are the two above: a teammate on Gemini CLI has to add the filename to their own settings.json, and a teammate on Claude Code will not see the file at all if the repository also contains a CLAUDE.md. Zed is worth knowing about for a different reason — it writes to the global AGENTS.md as well as reading it, so rules edited in the app land in the file.
Is it AGENT.md or AGENTS.md?
AGENTS.md, plural. The singular agent.md file was Amp's earlier name for the same thing, and Sourcegraph moved Amp to AGENTS.md on 20 August 2025. A tool that reads the plural will not find a file saved under the singular, so if instructions seem to be ignored, check the filename first.
Does Codex read AGENTS.md?
Yes. The Codex AGENTS.md file is documented in OpenAI's own Codex repository, which is the format's home. Searches for a Codex agent.md file, singular, lead nowhere: the filename OpenAI documents is AGENTS.md, and we have not seen a singular form documented for Codex.
Does OpenCode read AGENTS.md?
Yes, by default. An OpenCode AGENTS.md file in the project root is how SST's documentation says to give it custom instructions, and nothing needs to be switched on.
Where does this table come from?
Each row was read at an address the vendor itself publishes — its documentation site, its llms.txt index, or the docs inside its own repository — and carries the sentence it was read from. Nothing here is taken from the agents.md website's own list of supporting tools, because whether that list is accurate is the question. Verified 2026-09-19.
Every row verified 2026-09-19 against the linked page. 1 of 15 tools need a setting changed before AGENTS.md does anything. Compare these tools on price.