Claude Code reads AGENTS.md now — but five ordinary setups still leave it unread

Update — October 4, 2026: the stable channel has caught up. The native installer, npm and Homebrew’s default cask now install 2.1.285 on stable, which includes native AGENTS.md support without the telemetry requirement. Setup 4 below stops applying once your stable install updates (Homebrew installs still need brew upgrade). The other four setups are unchanged.

The 30-second version

On 18 September, Claude Code 2.1.277 started reading AGENTS.md, the shared instructions file that Codex, Cursor and many other coding agents already read. That was 32 days after Anthropic closed the most-upvoted request for it by pointing to a workaround (our August write-up).

By default it is a fallback, not a merge. Claude Code reads your AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or any folder above it.

We ran 108 headless sessions: 30 setups on Claude Code 2.1.283, the current release, and six of them again on 2.1.280. Every result was read from the session transcript, and every setup gave the same result in all three of its runs.

• A project with only an AGENTS.md loads it. So does .claude/AGENTS.md, and a root AGENTS.md when you start in a subfolder.
• Five ordinary setups leave it unread: a personal CLAUDE.local.md; a CLAUDE.md in any parent folder; a package’s AGENTS.md under a root CLAUDE.md; the stable release channel, which is still on 2.1.274; and versions 2.1.277 to 2.1.280 with telemetry turned off. We reproduced the first three on 2.1.283 and the last on 2.1.280. The stable case follows from its version number.
• The telemetry requirement reported this week was removed in 2.1.281 on 23 September. On 2.1.280, each of four variables that stop feature-flag fetching blocked AGENTS.md in 3 of 3 runs. On 2.1.283, none did.
• A one-line CLAUDE.md containing @AGENTS.md loaded the file it imports in all 21 of its runs, across seven setups and both versions, and never loaded it twice. In a monorepo it covers only the root file; each package needs its own.

Verdict: keep the one-line import. Native support is enough only when nobody on the project has a CLAUDE.md-type file on the path and everyone runs 2.1.281 or later. The import depends on neither.

How we tested

Each run built a fresh folder with git init, wrote the instruction files for one setup, and started Claude Code headless (claude -p) with Claude Haiku 4.5, a clean environment, and our own plugins and MCP servers switched off. Every instruction file held a different codeword, and we asked the model to list the codewords it had been given.

We didn’t rely on that answer. Claude Code records what it loads in the session transcript, a .jsonl file under ~/.claude/projects/: files loaded at startup in an instructions entry with each file’s path and content, and a subfolder’s file in a separate entry after Claude opens a file there. Those entries are our record of what loaded. The model’s answer agreed with them in 108 of 108 runs, and no file appeared twice in any session.

All 30 setups ran on 2.1.283 (90 runs). Six were repeated on 2.1.280 (18 runs), the last release before the telemetry fix. Three runs per setup and version, 402 seconds of run time and $2.04, on macOS on 26 September. We didn’t run 2.1.274 or 2.1.277 to 2.1.279; what we say about them comes from Anthropic’s release notes and documentation.

The rule: a fallback, not a merge

Default settings, Claude Code 2.1.283:

These results match Anthropic’s documented rules. The check walks from your working directory up to the top of the filesystem. Three things don’t count and keep loading alongside AGENTS.md: your personal ~/.claude/CLAUDE.md, an organisation’s managed CLAUDE.md, and .claude/rules/ files.

A subfolder’s AGENTS.md is not read at startup. It loads the first time Claude opens a file in that folder with the Read tool — as long as the fallback is active and that folder has no CLAUDE.md-type file of its own.

One side effect: with default settings on 2.1.277 or later, a repository’s AGENTS.md now goes into Claude’s context at startup whenever no CLAUDE.md-type file blocks it, the way a CLAUDE.md always has. Our attack-surface piece covers what files loaded at startup mean for security.

Five setups that leave it unread

Nothing tells you when this happens. In our headless runs no notice appeared either way. For interactive sessions, Anthropic documents a line that appears when AGENTS.md does load, reading AGENTS.md loaded: followed by the file paths. The bug reports for the skipped cases, issues #95690, #95589 and #96117, all say nothing appears when it doesn’t. We didn’t test interactive sessions. The dependable check is /memory, covered below.

1. A personal CLAUDE.local.md

CLAUDE.local.md is the per-developer file people keep out of git. It counts as a CLAUDE.md, so adding one drops the team’s AGENTS.md — for that one developer. Their teammates’ sessions still load it, so only one person’s results change. Anthropic documents this as intended: “Because CLAUDE.local.md counts, adding one to keep your own uncommitted instructions in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you.” An open bug report, issue #96117, asks Anthropic to stop counting CLAUDE.local.md.

2. A CLAUDE.md in any folder above

Under default settings, one CLAUDE.md in a parent folder switches off AGENTS.md for every session started below it, whether that folder is inside your git repository or outside it (3/3 each). Two examples: a CLAUDE.md at a monorepo root, and one left in your home folder. The exemption is for ~/.claude/CLAUDE.md, not ~/CLAUDE.md.

3. A package’s AGENTS.md under a root CLAUDE.md

In a monorepo with a root CLAUDE.md, a package’s own AGENTS.md doesn’t load under default settings: not when you start Claude in the package, and not when Claude opens files there from the root (3/3 each). That includes a root CLAUDE.md that only imports the root AGENTS.md. The import brings in the root file, and the package file stays unread (3/3). Codex, started in that package, reads the package’s AGENTS.md, because it looks from the repository root down to where you started.

4. The stable channel, and Homebrew’s default

Claude Code has two release channels. Anthropic describes stable as typically about a week old, skipping releases with major regressions; latest gets each version as it ships. On 26 September, stable installs 2.1.274 — for the native installer, on npm, and in Homebrew’s default claude-code cask — which predates AGENTS.md support. Homebrew installs don’t update themselves. A team on either reads AGENTS.md only through an import; claude --version tells you which version you’re on. If stable next lands on 2.1.277 to 2.1.280, the telemetry problem below applies.

5. Versions 2.1.277–2.1.280 with telemetry off

Before 2.1.281, native support was off in sessions that don’t fetch Anthropic’s feature flags. We reproduced that on 2.1.280 with each of the four variables above. According to the 2.1.281 release note, the same applied on Amazon Bedrock, Google Vertex AI, Microsoft Foundry and LLM gateways. Until 25 September, the 2.1.277 changelog entry listed only Bedrock, Vertex and Foundry as exceptions; a user reported the telemetry case as issue #95690 on 20 September.

2.1.281 fixed it on 23 September. In the two binaries we compared, the plugin’s on-by-default value is false in 2.1.280 and true in 2.1.283; both still check the remote flag, with that value as the default. So posts from this week that tell you to turn telemetry back on are out of date for 2.1.281 and later. On an older version, update — or use the import, which loaded with telemetry off on both versions we tested.

Anthropic’s docs list two cases that remain: the built-in agents-md plugin turned off in /plugin, and — which we couldn’t test — the first session after upgrading from 2.1.276 or earlier, which can miss the file until the next session.

Reading both files, and where the setting has to live

To keep Claude-only notes in CLAUDE.md and the shared rules in AGENTS.md without an import, set Project instructions in /config. The four values:

On 2.1.283, claude-md-and-agents-md loaded both files in every mixed setup we tried: CLAUDE.md with AGENTS.md, CLAUDE.local.md with AGENTS.md, a parent CLAUDE.md with a project AGENTS.md, and a root CLAUDE.md with a package AGENTS.md — the package file after Claude read a file there (3/3 each). That covers setups 1 to 3 above.

Where you set it matters. It works in your user settings (~/.claude/settings.json), in a file passed with --settings, and in managed settings. In the project’s .claude/settings.json it is ignored — we tried, and all three runs loaded CLAUDE.md only. So committing it to the repository doesn’t turn it on for your team. Each developer sets it, or an administrator pushes it through managed settings, under the built-in plugin’s ID:

{
  "pluginConfigs": {
    "agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Keep the one-line import

A CLAUDE.md containing only @AGENTS.md is the setup Anthropic documented before native support existed. In our runs it did what it says in every setup we put it in:

• It loaded the file it imports in all 21 of its runs: default settings, claude-md-and-agents-md, telemetry off on 2.1.280 and 2.1.283, next to a CLAUDE.local.md, and in two monorepo layouts.
• It never loaded AGENTS.md twice. The import counts as the CLAUDE.md, so the fallback stays off, and in claude-md-and-agents-md Claude Code skips an AGENTS.md it has already read. A CLAUDE.md symlinked to AGENTS.md behaved the same way.
• It works on versions before 2.1.277, which is what the stable channel installs today.
• It leaves room for Claude-only lines under the import.

One limit: an import brings in the file it names and nothing else. In a monorepo, give each package its own one-line CLAUDE.md. With one in sub/, the package’s AGENTS.md loaded as soon as Claude opened a file there (3/3).

The docs list one more difference in the import’s favour: InstructionsLoaded hooks fire for an imported AGENTS.md but not for one read natively.

Once you’ve confirmed Claude reads AGENTS.md, two older workarounds should go. The docs warn that a SessionStart hook printing AGENTS.md adds a second copy when Claude Code reads the file itself. And a CLAUDE.md that asks Claude in words to read AGENTS.md only works if the model decides to open the file; replace the sentence with a real @AGENTS.md line.

Codex reads a different set of files

Sharing one AGENTS.md doesn’t mean both agents read the same instructions:

• The override file. In its home folder (~/.codex by default) and in each folder from the project root down to where you started, Codex prefers a non-empty AGENTS.override.md over AGENTS.md. Claude Code doesn’t load it automatically (0 of 3 runs).
• Where each looks. Codex looks in its home folder, then in each folder from the project root (usually the git root) down to where you started. Claude Code looks in the folder where you started and every folder above it, past the edge of the repository, and in a subfolder only after it opens a file there.
• Size. Codex stops adding instruction files once they total 32 KiB, its default project_doc_max_bytes.
• Skills. Shopify’s CEO asked in August for AGENTS.md and .agents/skills. Native AGENTS.md support has shipped. Claude Code’s skills docs don’t mention .agents/skills, and its AGENTS.md docs list anything under .agents/ as not read. We didn’t test skills there.

How to check what your session loaded

First, claude --version. Native support needs 2.1.277 or later, and 2.1.281 or later if telemetry is off.

Interactive: run /memory and look for the AGENTS.md path. That works on 2.1.280 or later; earlier versions didn’t list an AGENTS.md loaded this way.

Headless or in CI, use the check we used, reading the transcript:

sid=$(claude -p "ok" --output-format json | jq -r .session_id)
jq -r 'select(.attachment.type? == "instructions") | .attachment.files[] | "\(.type)\t\(.path)"' \
  ~/.claude/projects/*/"$sid".jsonl

It prints one line per file loaded at startup, such as Project /repo/AGENTS.md. A subfolder’s AGENTS.md is recorded separately when Claude opens a file there, so it won’t show here. The transcript format isn’t documented and can change; /memory is the supported check.

What we didn’t test

• Versions 2.1.274 and 2.1.277 to 2.1.279, and Bedrock, Vertex, Foundry and gateways. For these we rely on Anthropic’s release notes and documentation.
• Interactive and background sessions. Issue #95589 reports AGENTS.md loading in some interactive sessions and not others on 2.1.278. Our headless runs were consistent: every setup gave the same result three times out of three.
• Windows, and the first session after an upgrade.
• Obedience. We checked that the file loaded, not how closely Claude follows it when it arrives natively versus through the import.

Companion reading

• CLAUDE.md vs AGENTS.md — which one does Claude Code actually read? — the quick answers, updated for native support.
• Shopify’s CEO threatened to ban Claude Code over AGENTS.md — the August dispute, and the bridges we tested then on 2.1.243.
• AGENTS.md template — a lean starter file and the one-line import.
• Anthropic deleted 80% of Claude Code’s system prompt — what instruction files do and don’t change in agent results.
• Your CLAUDE.md is an attack surface — why files loaded at startup matter for security, now that AGENTS.md is one of them.

Sources

1. Anthropic — Manage Claude’s memory: AGENTS.md. The default rule, which files count, the four Project instructions values, where the setting is ignored, what isn’t read, how native loading differs from an import, and the note on CLAUDE.local.md quoted above.
2. Anthropic — Claude Code changelog. 2.1.277 added AGENTS.md support, with “(not yet on Bedrock, Vertex or Foundry)” in the entry until 25 September; 2.1.281 extended it to Bedrock, Vertex, Foundry, LLM gateways and sessions with telemetry disabled.
3. Anthropic — Environment variables. Which variables stop feature-flag fetching, and the first session after an install or upgrade.
4. Anthropic — Set up Claude Code. The latest and stable release channels, and Homebrew’s two casks.
5. npm — @anthropic-ai/claude-code. Release times (2.1.277 on 18 September, 2.1.281 on 23 September) and dist-tags on 26 September: stable 2.1.274, latest 2.1.283. The native installer’s channel files, stable and latest, gave the same two versions.
6. Homebrew — claude-code (2.1.274) and claude-code@latest (2.1.283), on 26 September.
7. GitHub — issue #95690, AGENTS.md support gated by a remote feature flag, filed 20 September.
8. GitHub — issue #96117, CLAUDE.local.md switches off the fallback, filed 22 September, open.
9. GitHub — issue #95589, intermittent loading in interactive sessions on 2.1.278, open.
10. OpenAI — Codex: AGENTS.md. Override file, where Codex looks, and the 32 KiB default limit.
11. blog.szypowi.cz — Claude Code reads AGENTS.md only when telemetry is on, 23 September. Accurate for 2.1.277 to 2.1.280.
12. DEV Community — Claude Code AGENTS.md support needs telemetry turned on, 26 September, three days after 2.1.281 shipped.

Our own measurements: 108 claude -p sessions on macOS on 26 September 2026 with Claude Haiku 4.5 — 30 setups on Claude Code 2.1.283 and six of them again on 2.1.280, three runs each. Startup files come from the transcript’s instructions entry, and subfolder files from the entries recorded after Claude opened a file there. The model’s answer matched those records in 108 of 108 runs, and no file appeared twice in any session. Total cost $2.04. The on-by-default comparison is from the bundled agents-md plugin in each version’s binary.

FAQ

Does Claude Code read AGENTS.md now? Yes, since 2.1.277 on 18 September — by default as a fallback. It reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your working directory or above it. With both files present and default settings, only CLAUDE.md loaded in our runs on 2.1.283.

Why isn’t it loading my AGENTS.md? Check for a CLAUDE.local.md, a CLAUDE.md in a parent folder, a root CLAUDE.md above the package you’re in, the stable channel or Homebrew’s default cask (2.1.274), and a version from 2.1.277 to 2.1.280 with telemetry off. Then run claude --version and /memory.

Does it need telemetry? Not since 2.1.281 on 23 September. On 2.1.280, each of four variables that stop feature-flag fetching blocked it in 3 of 3 runs; on 2.1.283, none did.

Can I delete my @AGENTS.md import? You can, but it loaded the imported file in all 21 of its runs and never loaded it twice. Check with /memory what your team’s versions and settings load before removing it. In a monorepo, each package needs its own.

How do I load both files? Set Project instructions to claude-md-and-agents-md in /config or your user settings. A project’s .claude/settings.json can’t set it.

Does Claude Code read AGENTS.override.md? Not automatically, and Codex prefers it. Neither AGENTS.local.md nor anything under .agents/ loads either.