Claude Code v2.1.277, released on 18 September 2026, can read AGENTS.md as a project's instruction file. The changelog entry is one sentence: "Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under 'Project instructions' in /config (not yet on Bedrock, Vertex or Foundry)." That closes the last conspicuous gap in the AGENTS.md standard, which is used by more than 60,000 open-source projects and read natively by Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, Zed, Factory, Jules and roughly twenty other tools. Claude Code was the holdout.
The documentation tells a more conditional story than the changelog does. Support is a feature-flagged built-in plugin, not a client behaviour. It switches off when you set DO_NOT_TRACK, when you run on Amazon Bedrock or Microsoft Foundry, and in the first session after you upgrade. It loads the file without listing it anywhere you would look to audit your context. And the setting that controls it is ignored in project and local settings files, so the one choice a team would want to commit alongside the portable file cannot be committed at all.
What Anthropic Shipped
The release landed as v2.1.277 on the afternoon of 18 September, one version after a hotfix for a proxy regression in 2.1.275. The behaviour is documented in full on the project memory page, which now carries a dedicated AGENTS.md section rather than a passing mention.
The default is not "read both." It is "read AGENTS.md only if no CLAUDE.md exists." Anthropic's own precedence table:
| Your repository has | Claude reads |
|---|---|
An AGENTS.md, and no CLAUDE.md or CLAUDE.local.md in your working directory or above it | Your AGENTS.md |
An AGENTS.md and a CLAUDE.md or CLAUDE.local.md in your working directory or above it | Your CLAUDE.md files only |
A CLAUDE.md that already imports AGENTS.md | Your CLAUDE.md, with AGENTS.md included through the import |
When the file does load, it loads properly rather than as a token gesture. Claude reads every AGENTS.md and .claude/AGENTS.md in the working directory and the directories above it, picks up a subdirectory's AGENTS.md when it opens a file there with the Read tool, expands @path imports inside the file, and applies claudeMdExcludes patterns. What it does not read is AGENTS.local.md, AGENTS.override.md, or anything under a .agents/ directory.
The standard itself is no longer an OpenAI house format. AGENTS.md originated in OpenAI's Codex tooling and was contributed to the Agentic AI Foundation when the Linux Foundation formed it in December 2025, alongside Anthropic's own Model Context Protocol and Block's goose. Anthropic is a platinum member of the foundation that stewards the file its flagship coding tool has spent nine months not reading.
The Four Conditions That Switch It Off
The changelog's parenthetical, "not yet on Bedrock, Vertex or Foundry," understates the constraint. AGENTS.md support is gated behind a feature flag Claude Code fetches from Anthropic, and it is the first item on the list of features that stop working when that fetch is skipped. Four separate situations skip it.
Privacy environment variables. Setting DISABLE_GROWTHBOOK, DISABLE_TELEMETRY, DO_NOT_TRACK, or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC turns flag fetching off. DO_NOT_TRACK is a cross-vendor convention that many developers set globally and never think about again. Setting it now silently costs you the ability to read a portability standard's instruction file.
Third-party providers. A session on a third-party provider, including Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform and Microsoft Foundry, skips the fetch unless a host platform sets CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST. This is the inversion worth naming: the population most likely to have a cross-tool instruction file mandated by a platform team is the enterprise population, and the enterprise population is the one routed through Bedrock and Foundry.
The first session after you upgrade. Claude Code fetches the flags during that session, so the feature appears from your next session on. Anyone who upgrades to 2.1.277, opens a repository to test the new behaviour and sees nothing will have tested it in the exact session where it cannot work.
Hook restrictions. Support ships as a built-in plugin called agents-md. Setting disableAllHooks or allowManagedHooksOnly, or disabling that plugin in /plugin, removes it. In all four cases Project instructions does not appear in the /config panel at all, so the setting's absence is the only diagnostic you get.
Why CLAUDE.local.md Is the One That Bites
The precedence rule turns on what counts as a CLAUDE.md, and the answer is narrower than "a file named CLAUDE.md." Three files count and block AGENTS.md: a CLAUDE.md, a .claude/CLAUDE.md, or a CLAUDE.local.md, in the working directory or any directory above it. Three do not count, and keep loading alongside AGENTS.md: your personal ~/.claude/CLAUDE.md, your organisation's managed CLAUDE.md, and .claude/rules/ files.
CLAUDE.local.md is the trap, and Anthropic flags it directly: adding one to keep your own uncommitted notes in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you. It is a gitignored, personal, per-developer file. Your teammates keep reading the shared instructions and you quietly stop, with nothing in the diff to explain the divergence. The fix is to set Project instructions to claude-md-and-agents-md, which is a per-machine change each affected developer has to make individually.
The same "in your working directory or above it" clause means a stray CLAUDE.md in a parent directory, a home directory checkout or an outer monorepo folder, disables AGENTS.md for every repository beneath it.
It Loads Where You Cannot See It
An AGENTS.md read through the setting behaves differently from a CLAUDE.md in four documented ways, and the first two are observability gaps. It is not listed in /memory or in the Memory files list in /context. And InstructionsLoaded hooks do not fire for it, though they fire as usual for an AGENTS.md that a CLAUDE.md imports or symlinks to.
So the two mechanisms you would use to audit what is in an agent's context, the context inspector and the instruction-load hook, both report nothing while the file is loaded and in effect. Anthropic's suggested confirmation is to look for a line reading no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md at session start, or to ask Claude what its project instructions say. For teams that built CI checks or audit tooling on InstructionsLoaded, that tooling goes blind on any repository that switches from an imported AGENTS.md to a directly read one.
Two smaller differences round out the list. Directories added with --add-dir load their CLAUDE.md when CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD is set, but never their AGENTS.md. And an @path import pointing outside the working directory, which normally triggers an approval prompt, loads with no prompt if you approved external imports for that project at any point in the past.
The Setting You Cannot Commit
Four values are available under Project instructions, and the choice matters more than the default suggests.
| Value | What Claude reads |
|---|---|
claude-md-or-agents-md | CLAUDE.md files, or AGENTS.md when no CLAUDE.md or CLAUDE.local.md sits in the working directory or above it. The default |
claude-md-and-agents-md | Both, each directory's CLAUDE.md first and its AGENTS.md after. An AGENTS.md already loaded through an import or symlink is not read twice |
claude-md | CLAUDE.md files only, the pre-2.1.277 behaviour |
managed-only | Only the organisation's managed CLAUDE.md and auto memory at launch. Project, local and user CLAUDE.md files, .claude/rules/ and every AGENTS.md are left out |
You can set the value outside /config by writing it under the built-in plugin's ID in pluginConfigs, as "agents-md@builtin": {"options": {"instructionFiles": "claude-md-and-agents-md"}}. The constraint is in the next sentence of the documentation: it is accepted in ~/.claude/settings.json, a --settings file, or managed settings, and Claude Code ignores it in project and local settings files.
That is the structural point. AGENTS.md exists so a repository can ship one instruction file that every tool honours. The setting deciding whether Claude Code honours it lives on each developer's machine or in an organisation-wide managed policy, and cannot travel in the repository. A team can commit the portable file; it cannot commit the decision to read it. The realistic path for an organisation that wants consistency is managed settings, which is available on Team and Enterprise plans rather than to the open-source projects that make up most of the 60,000.
What To Do With Your Existing Workaround
Most repositories that wanted this already faked it, and the four common workarounds need four different responses.
A CLAUDE.md containing @AGENTS.md can stay. Keeping the import never causes a double read under any Project instructions value, and it is still the only thing that works on Bedrock, Foundry, or with DO_NOT_TRACK set. Delete the CLAUDE.md only if it holds nothing else.
A CLAUDE.md that tells Claude in words to go read AGENTS.md was always the weakest version, since Claude only sees the file if it decides to open it. Delete that CLAUDE.md, or replace the sentence with a real @AGENTS.md import.
A CLAUDE.md symlinked to AGENTS.md needs nothing. Note that the Edit and Write tools refuse to write through a symlink and will redirect Claude to edit AGENTS.md directly, and that the link needs care on Windows for anyone cloning the repository.
A SessionStart hook that prints AGENTS.md must be removed. Once Claude reads the file directly, that hook appends a second copy to the context on every session. This is the only workaround where doing nothing actively costs you tokens, and it is worth checking for before you upgrade a team.
Frequently asked questions
Does Claude Code read AGENTS.md if I also have a CLAUDE.md?
Not by default. With the default claude-md-or-agents-md setting, any CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it means Claude reads CLAUDE.md files only. Set Project instructions to claude-md-and-agents-md to load both, CLAUDE.md first.
Which version added AGENTS.md support?
Claude Code v2.1.277, released 18 September 2026. Earlier versions read CLAUDE.md files only and do not show the Project instructions entry in /config.
Why does the Project instructions setting not appear in my /config panel?
Four reasons: you are on a version before 2.1.277; your session skips feature-flag fetching because of DISABLE_GROWTHBOOK, DISABLE_TELEMETRY, DO_NOT_TRACK, CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC, a third-party provider such as Bedrock or Foundry, or a Claude apps gateway session; it is your first session after installing or upgrading; or hooks are restricted through disableAllHooks or allowManagedHooksOnly.
How do I confirm Claude actually read my AGENTS.md?
Look for the no CLAUDE.md found; AGENTS.md loaded: /path/to/AGENTS.md line at session start, or ask Claude what its project instructions say. It will not appear in /memory or in the Memory files list in /context, and InstructionsLoaded hooks will not fire for it.
Can my team commit the AGENTS.md setting to the repository?
No. The pluginConfigs entry for agents-md@builtin is read from ~/.claude/settings.json, a --settings file, or managed settings only. Claude Code ignores it in project and local settings files, so each developer sets it individually unless your organisation pushes it through managed settings.
Does it read nested AGENTS.md files in a monorepo?
Yes, with a condition. Every AGENTS.md and .claude/AGENTS.md at or above the working directory loads at session start, and a subdirectory's file loads when Claude opens a file there with the Read tool, provided that subdirectory has none of the three CLAUDE.md variants of its own.
Does this work on Amazon Bedrock or Microsoft Foundry?
Not currently. Those sessions skip feature-flag fetching, so Claude reads CLAUDE.md files only. Put an @AGENTS.md import in a CLAUDE.md next to the file, which works everywhere and never double-loads on sessions that do support direct reading.
