AGENTS.md in Claude Code

What AGENTS.md is

AGENTS.md is a markdown file of project instructions for coding agents. The site that carries it calls it "a simple, open format for guiding coding agents", and describes it as a README for agents rather than for the people reading the repository. The reason for a second file is the split in audience: a README covers quick starts and contribution notes for humans, while AGENTS.md carries the build steps, the test commands and the conventions an agent needs. The site says the format was chosen to work for anyone rather than being tied to one vendor.

There is no specification to comply with. Asked whether any fields are required, the site answers that AGENTS.md is just standard Markdown and that you can use any headings you like. A file you write today is readable by every tool on the support list, though two of them need a line of configuration first: the site keeps a separate entry for Aider and one for Gemini CLI.

Who maintains it has changed. The site's copyright line reads "AGENTS.md a Series of LF Projects, LLC", and a line above it says the format is now stewarded by the Agentic AI Foundation under the Linux Foundation. The site carries no version number and no publication date, so the state of the format is whatever the page says on the day you open it.

The support list is long and it is on the page itself: Codex from OpenAI, Jules from Google, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin from Cognition, Autopilot and Coded Agents from UiPath, Junie from JetBrains, Amp, Cursor, RooCode, Gemini CLI from Google, Kilo Code, Phoenix, Semgrep, the coding agent from GitHub Copilot, Ona, Windsurf from Cognition, and Augment Code. The page's own measure of adoption is a GitHub search that it says returns over 60,000 open-source projects, and its example of scale is the main OpenAI repository, which carries 88 AGENTS.md files.

Files nest, and the nearest one wins. The site tells you to place another AGENTS.md inside each package, because agents read the closest file in the directory tree and let it take precedence over the one above. On a conflict between two, the site's rule is that the AGENTS.md closest to the file being edited wins, and that anything you type in chat overrides both.

What Claude Code reads today

Claude Code can read a repository's AGENTS.md as its project instructions. In Anthropic's words, Claude reads your AGENTS.md when you have "an AGENTS.md, and no CLAUDE.md or CLAUDE.local.md in your working directory or above it". Anthropic publishes the whole decision as a table of three cases, and this is the default.

The version matters, and it is recent. Anthropic says reading AGENTS.md directly requires Claude Code v2.1.277 or later, and npm published that release on 18 September 2026. Check yours with claude --version before you go looking for anything subtler.

Anthropic draws a careful line between the files that count against AGENTS.md and the files that do not. A CLAUDE.md, a .claude/CLAUDE.md or a CLAUDE.local.md in your working directory or any directory above it counts, and one of those is enough to switch AGENTS.md off. Three other things keep loading alongside it instead: your own ~/.claude/CLAUDE.md, the managed CLAUDE.md your organization deploys, and the rule files under .claude/rules/. A personal instructions file at user scope is therefore not what breaks AGENTS.md, so it is not the thing to go looking for.

When Claude reads AGENTS.md in place of CLAUDE.md, an interactive session says so. A line such as no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md appears in the conversation. Anthropic also lists what loads besides the file at the top of the tree: a subdirectory's own AGENTS.md arrives when Claude opens a file there and that subdirectory holds none of the three CLAUDE.md names, and the @path imports inside an AGENTS.md are expanded just as they are in a CLAUDE.md.

Three names are never read at all: AGENTS.local.md, AGENTS.override.md, and anything inside a .agents directory. If you have been keeping an override file and wondering why it does nothing, that is the answer, and Anthropic's own wording is that these are not read.

Two guides go further on the surrounding setup: running several Claude Code sessions at once covers worktrees, usage limits and keeping several sessions in view, and running many coding agents covers which harness to pick for each kind of work.

Why a setup stops working

This is the failure people write in about. Anthropic's own troubleshooting opens by naming it: when a repository has an AGENTS.md and Claude seems not to know what it says, the usual cause is a CLAUDE.md somewhere on the project path. The swap is not announced. A session that does read AGENTS.md prints a line saying so, such as no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md, so a session that reads your CLAUDE.md instead prints no such line and gives you no sign that anything changed. The file stays on disk, still correct, and no longer read.

Anthropic names the trap directly. Because CLAUDE.local.md counts in the check, a personal notes file added to a project that relies on AGENTS.md is enough to switch AGENTS.md off for that person alone, while every teammate without one still reads it. So the same repository can behave differently for two people, and the symptom looks intermittent when you compare notes with somebody else.

The check Anthropic prescribes runs in three steps. Look for a CLAUDE.md, a .claude/CLAUDE.md or a CLAUDE.local.md in your working directory or any directory above it, setting aside your own ~/.claude/CLAUDE.md. Run claude --version and confirm v2.1.277 or later, and v2.1.281 or later if the machine has telemetry turned off or runs on Amazon Bedrock. Then open /config and confirm the Project instructions setting is not set to claude-md or managed-only.

Two smaller traps sit beside the main one. Before v2.1.280, the /memory and /context lists did not show an AGENTS.md that Claude had read directly, so the file could be working while appearing to be absent from every list you could check. And the first session after you upgrade from v2.1.276 or earlier can be one that does not read AGENTS.md at all, whichever setting you have; Anthropic says it reads AGENTS.md from your next session on.

One more case is not a bug at all. AGENTS.md is read through a plugin that ships with Claude Code, so turning that plugin off in /plugin turns the feature off too, and the Project instructions setting disappears from the settings panel when it happens. If the setting is missing from /config, you are in a session that cannot read AGENTS.md.

The setups people built, and what the docs say now

Before Claude Code read AGENTS.md on its own, the only way to get one read was to route it through CLAUDE.md. Those setups still exist in repositories today, so Anthropic documents what to do with each.

• A CLAUDE.md that imports AGENTS.md. Anthropic's answer is that you can leave it alone. Keeping the import never makes Claude read AGENTS.md twice, whichever Project instructions value you use. Keep the CLAUDE.md if it carries anything else, or if some of your sessions cannot load AGENTS.md directly; remove it if it holds nothing but the import.
• A CLAUDE.md that tells Claude in words to read AGENTS.md. This one works only if Claude decides to open the file, which is not the same as being told to. Anthropic's fix is to delete the CLAUDE.md so Claude reads AGENTS.md directly, or to replace the sentence with an @AGENTS.md import.
• A CLAUDE.md symlinked to AGENTS.md. Anthropic says to do nothing, or to delete the symlink. Either way the content is read once.
• A SessionStart hook that prints AGENTS.md. Remove it. Once Claude reads AGENTS.md directly, Anthropic says the hook adds a second copy to the context.

If you still want one shared file after all of this, two routes remain and Anthropic documents both. An import line reading @AGENTS.md at the top of a CLAUDE.md works everywhere, and anything Claude-specific goes below it, because Claude reads the imported file first. A symlink of CLAUDE.md pointing at AGENTS.md also works.

Anthropic gives one reason to prefer the import that has nothing to do with your operating system: its Edit and Write tools refuse to write through a symlink and send Claude to the target instead, so a session editing the shared file takes a detour. The second reason is Windows-specific. Anthropic says that if you or anyone who clones the repository works there, use the import instead: a symlink needs Administrator rights or Developer Mode to create, and git checks a committed symlink out as a plain text file unless core.symlinks is enabled, which leaves that clone with a one-line CLAUDE.md in place of your instructions. Our page on Claude Code on Windows covers the rest of what differs there.

Changing which instruction files load

The default is not fixed. Anthropic puts the choice in a Project instructions setting, opened by typing /config in a session, with four values.

• claude-md-or-agents-md is the default and the behaviour described above: your CLAUDE.md files, or your AGENTS.md files when no CLAUDE.md or CLAUDE.local.md exists at or above your working directory.
• claude-md-and-agents-md reads both, each directory's CLAUDE.md first and its AGENTS.md after it. Claude Code skips an AGENTS.md it has already loaded, so one that your CLAUDE.md imports or links to is not read a second time.
• claude-md reads your CLAUDE.md files and nothing else.
• managed-only reads only your organization's managed CLAUDE.md and auto memory at launch, leaving out project, local and user CLAUDE.md files, your .claude/rules files and every AGENTS.md. A subdirectory's CLAUDE.md, its rule files and path-scoped rules still load when Claude works there.

A change takes effect from your next message and in every new session. If you would rather keep the choice in a file than in a panel, the same setting lives under pluginConfigs in ~/.claude/settings.json, keyed by the built-in plugin cc-plugin-agents-md@builtin. Anthropic reads that entry from your user settings, a --settings file or managed settings, and ignores it in project and local settings files. Before v2.1.285 the plugin's identifier was agents-md@builtin, and both are read on v2.1.285 and later.

Two more routes bring the file in rather than reading it in place. Anthropic's /init command incorporates other tools' instruction files into the CLAUDE.md it writes, and AGENTS.md is one of them when the CLAUDE_CODE_NEW_INIT variable is set to 1. The /import command appends a one-time copy of AGENTS.md to the matching CLAUDE.md and carries over MCP servers, commands, subagents and skills with it. A copy is a fork, so the two can drift from then on.

Where AGENTS.md behaves differently from CLAUDE.md

An AGENTS.md that Claude reads through the Project instructions setting is not quite the same as a CLAUDE.md, and Anthropic lists three differences. All three are small, and all three can surprise you in a session that depends on one of them.

• InstructionsLoaded hooks do not fire. A CLAUDE.md triggers them; an AGENTS.md read through the setting does not. They do fire normally for an AGENTS.md that a CLAUDE.md imports or symlinks to, so a hook-based setup is a reason to prefer the import.
• Directories you add with --add-dir keep their AGENTS.md out. With CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD set, an added directory's CLAUDE.md loads and its AGENTS.md does not.
• An import that reaches outside your working directory loads without a prompt. A CLAUDE.md importing a file from outside gets an approval dialog the first time. An AGENTS.md loading the same import does so silently, but only if you have already approved external imports for that project.

Everything else follows the CLAUDE.md rules you already know. Instructions are context rather than enforced configuration, and Anthropic recommends keeping a file under 200 lines because longer files consume more context and reduce adherence. A project-root instructions file survives compaction and is re-read from disk afterwards, while path-scoped rules and a subdirectory's file load again on demand.

Where the request for the feature stands

The request that carried this feature is the most-reacted issue in Anthropic's claude-code repository, and not by a small margin. Issue 6235, titled "Feature Request: Support AGENTS.md.", was opened on 21 August 2025 by a user arguing that CLAUDE.md serves Claude Code well and other tools poorly. On 24 October 2026 it carried 6,688 reactions and 409 comments, and it is closed, marked completed on 17 August 2026. The next issue down the same ranking held 3,286 reactions, so the gap is close to double, and the repository carries 101,636 issues for it to lead.

The closure did not end the thread's family. Issue 31005, opened on 5 March 2026 and still open on 24 October 2026, asks for AGENTS.md and the .agents/skills directory together, and it carries 572 reactions and 37 comments. Its own body reported the older issue at 3,020 upvotes and 224 comments at the time it was written, which is a useful measure of how fast the demand kept growing. It is labelled a duplicate, and Anthropic's documentation covers the AGENTS.md half of it and not the skills directory.

Closing the issue did not add the feature. The one reply from Anthropic on that thread came from a collaborator, posted as the issue closed on 17 August 2026, and it points at a workaround rather than at support: "Claude Code reads CLAUDE.md, but you can share one file with other agents: create a CLAUDE.md containing just @AGENTS.md (an import), or symlink CLAUDE.md to AGENTS.md." Reading AGENTS.md on its own arrived later, in v2.1.277, which npm published on 18 September 2026.

The requests still open are about something else: the skills directory the older issue never covered. Anthropic's docs do not list a .agents directory as a place Claude Code reads, and the one line its memory page gives for that directory is that files under it are not read.

Where Omniscio fits

Tools in this family default to different files for the same job: Claude Code starts at a CLAUDE.md, Gemini CLI reads a GEMINI.md, Cursor reads a .cursorrules, and Copilot reads a .github/copilot-instructions.md. Omniscio has a feature for that. Agent Instructions Sync keeps one canonical file, your CLAUDE.md or your AGENTS.md, and writes copies of it to the other filenames the other tools look for: AGENTS.md, GEMINI.md, .cursorrules, .clinerules/base.md, .github/copilot-instructions.md and .windsurfrules. You pick which of the two is the source of truth in the feature's settings, and AGENTS.md is listed for Codex, Gemini, Cursor and the other agent-aware tools.

The feature is off by default, and switching it on changes nothing in a project that has no canonical file. Each copy carries a short banner saying it is machine-managed, and a copy somebody edited by hand is never overwritten silently: Omniscio raises a conflict dialog in the sidebar and an inbox card, and you choose whether to discard the edit, promote it to become the new source of truth, or stop syncing that file. It is a small background job rather than a build step, so editing the canonical updates the copies on the next pass.

There is a second, separate mechanism that touches the same files. Omniscio runs sessions on several engines, and each engine reads its own project file: Codex reads AGENTS.md, Gemini reads GEMINI.md, Cursor reads .cursorrules. When one of those copies is present and matches your canonical file, Omniscio does not repeat the same rules in the session's opening instructions, because the engine will read the file for itself. When the copy is absent, stale or hand-written, it sends the rules in the prompt instead, so no engine is ever left with none of them.

Two library pages carry the detail: Agent Instructions Sync for the mirroring, the drift handling and the git choices, and Repo Foundations for the one-time setup that picks your canonical file and turns the mirroring on. If you run more than one engine, provider config sync covers the global instructions file each tool reads, which is a different file from the project one.

Omniscio does not change what Claude Code reads, and nothing here overrides the rule in Anthropic's documentation. What it does is keep the other tools' files current, so the instructions you write once reach every agent in the project.