Claude Code Now Reads AGENTS.md: Setup, Modes and Gotchas

Since v2.1.277 (published to npm on September 18, 2026), Claude Code reads a repository's AGENTS.md as its project instructions whenever there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it. No import, symlink or setting is needed. The verdict: if your team already keeps one AGENTS.md for Codex and other agents, you can drop the one-line @AGENTS.md shim in most setups - but one rule decides everything, and it catches people: any CLAUDE.md or CLAUDE.local.md on the path silently wins, unless you switch Project instructions to claude-md-and-agents-md.

Last updated: October 17, 2026

What shipped, and when#

The Claude Code changelog entry for 2.1.277 reads:

Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under "Project instructions" in /config

Several follow-up releases shaped how it behaves today. Dates are from the npm registry:

The 2.1.281 change has a backstory about the feature being gated in some sessions at launch; we covered it in the September 25 weekly highlights, so it is not retold here. As of today, npm's latest tag is 2.1.302 and stable is 2.1.292, so both channels include every fix above.

The 2.1.290 fix mentions permissions.blockReadsOutsideWorkingDirectories. That key, and the write-side permissions.blockWritesOutsideWorkingDirectories added in 2.1.314, are explained in our guide to keeping Claude Code's edits inside the project.

One structural detail is worth knowing up front: the loader is not core engine code. It is a built-in plugin (a mod) whose source is published in the Claude Code repository under mods/agents-md. That explains why /plugin can switch it off and why its settings key lives under pluginConfigs. If mods are new to you, our Claude Code mods guide explains what they can and cannot do.

How Claude Code decides which file to read#

The memory docs reduce the default behavior to three cases:

• An AGENTS.md, and no CLAUDE.md or CLAUDE.local.md in your working directory or above it: Claude reads your AGENTS.md.
• An AGENTS.md and a CLAUDE.md or CLAUDE.local.md there: Claude reads your CLAUDE.md files only.
• A CLAUDE.md that already imports AGENTS.md: Claude reads the CLAUDE.md, with AGENTS.md included through the import.

The important question is what "a CLAUDE.md" means for that check. The docs are specific:

• Counts (and so suppresses AGENTS.md): a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or any directory above it.
• Does not count (keeps loading alongside AGENTS.md): your ~/.claude/CLAUDE.md, your organization's managed CLAUDE.md, and .claude/rules/ files.

So your personal global instructions and your team's rules directory are safe. A stray CLAUDE.md in a parent directory - say, a monorepo root someone added months ago - is not.

%% title: Which file Claude Code reads by default
flowchart TD
  A[Session starts in a directory] --> B{CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md here or above?}
  B -- Yes --> C[Load CLAUDE.md files only]
  B -- No --> D{AGENTS.md here or above?}
  D -- Yes --> E[Load every AGENTS.md and .claude/AGENTS.md on the path]
  D -- No --> F[No project instructions]
  C --> G[User and managed CLAUDE.md, .claude/rules still load]
  E --> G

When AGENTS.md files enter the context#

Per the docs, there are two moments when Claude picks up AGENTS.md content.

At session start, Claude reads every AGENTS.md and .claude/AGENTS.md in the working directory and the directories above it. In an interactive session, the docs say you see a line such as:

no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

As Claude works in subdirectories, a subdirectory's AGENTS.md loads when Claude opens a file there with the Read tool, as long as that subdirectory has none of the three CLAUDE.md files of its own. This mirrors how nested CLAUDE.md files already behave, and it means a monorepo with packages/api/AGENTS.md does not pay for that file until Claude actually touches the API package.

Inside each AGENTS.md, @path imports are expanded (imports can recurse up to four hops), and claudeMdExcludes patterns apply. That means you can exclude a vendored package's AGENTS.md the same way you would exclude its CLAUDE.md.

What Claude Code does not read: AGENTS.local.md, AGENTS.override.md, or anything under a .agents/ directory. If you came from Codex and rely on override files, read the comparison section below.

%% title: When AGENTS.md files enter the context
sequenceDiagram
  participant U as You
  participant CC as Claude Code
  participant P as agents-md plugin
  participant FS as Repo files
  U->>CC: claude (in repo/)
  CC->>P: build project instructions
  P->>FS: walk cwd and parents for AGENTS.md
  FS-->>P: repo/AGENTS.md
  P-->>CC: add as project instruction file
  CC-->>U: no CLAUDE.md found, AGENTS.md loaded
  U->>CC: fix a bug in packages/api
  CC->>FS: Read packages/api/src/server.ts
  P->>FS: check packages/api for AGENTS.md and no CLAUDE.md
  P-->>CC: attach packages/api/AGENTS.md after the Read result

Step-by-step setup#

If you still need to install Claude Code, start with our Claude Code setup guide. Then:

1. Check your version.

claude --version

You need 2.1.277 or later. You need 2.1.281 or later if you run on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, an LLM gateway, or with telemetry disabled. You need 2.1.285 or later if you want to use the cc-plugin-agents-md@builtin settings key. To upgrade:

claude update

2. Put AGENTS.md at the repo root and clear the path. Make sure there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the directory you launch from or in any parent. A quick way to check from the repo root, for the parents too:

d="$PWD"; while [ "$d" != "/" ]; do ls "$d"/CLAUDE.md "$d"/.claude/CLAUDE.md "$d"/CLAUDE.local.md 2>/dev/null; d="$(dirname "$d")"; done

Any path this prints will suppress AGENTS.md under the default mode. Your ~/.claude/CLAUDE.md does not count, even though this loop prints ~/.claude/CLAUDE.md if your repo lives directly under your home directory - ignore that one.

3. Start a session with claude and look for the AGENTS.md loaded line.

4. Confirm what loaded. Run /memory and look for the AGENTS.md path, or run /context and look under Memory files. On versions before 2.1.280 neither listed a directly read AGENTS.md; on those, the docs suggest asking Claude what its project instructions say.

5. Optional: pick a mode. Type /config and find Project instructions. If the row is missing entirely, you are in a session where AGENTS.md support is unavailable (see the gotchas below).

The four Project instructions values#

The docs define four values:

managed-only is stricter than it sounds. At launch it leaves out project, local and user CLAUDE.md files, .claude/rules/ files, and every AGENTS.md. A subdirectory's CLAUDE.md and .claude/rules/ files, plus path-scoped rules, still load on demand.

The dedupe in claude-md-and-agents-md is the useful part. Turning the mode on in a repo where CLAUDE.md already contains @AGENTS.md does not double the file in your context.

%% title: The four Project instructions values
flowchart LR
  S["/config - Project instructions"] --> M1[claude-md-or-agents-md<br/>default]
  S --> M2[claude-md-and-agents-md]
  S --> M3[claude-md]
  S --> M4[managed-only]
  M1 --> R1[CLAUDE.md, else AGENTS.md]
  M2 --> R2[CLAUDE.md first, then AGENTS.md per directory]
  M3 --> R3[CLAUDE.md only]
  M4 --> R4[Managed CLAUDE.md and auto memory at launch]

Set it in settings.json instead of /config#

You can set the mode in a settings file under pluginConfigs, keyed by the built-in plugin's ID:

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

Where it is read matters. Claude Code reads this entry from ~/.claude/settings.json, a --settings file, or managed settings, and ignores it in project and local settings files. You cannot commit the mode into a repo's .claude/settings.json and expect teammates to pick it up. If you need a repo-level guarantee, commit a CLAUDE.md with an @AGENTS.md import instead (more on that below).

The plugin ID changed in 2.1.285. Before that release the ID was agents-md@builtin, and an entry under cc-plugin-agents-md@builtin was ignored. Version 2.1.285 and later read either ID. If the same settings file is shared by machines on older versions, put the block under both keys:

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

A changed value applies from the next message you send and in every new session, so there is no need to restart.

Migrating off the old workarounds#

Before 2.1.277, teams used one of four workarounds to get AGENTS.md into Claude Code. The docs say what to do with each:

• A CLAUDE.md containing @AGENTS.md: you can leave it. Keeping the import never makes Claude read AGENTS.md twice, whichever mode you use. Delete the CLAUDE.md if it holds nothing else, or keep it if some of your sessions cannot load AGENTS.md directly.
• A CLAUDE.md that tells Claude in prose to read AGENTS.md: replace it. With prose, Claude only sees AGENTS.md if it decides to open the file. Delete the CLAUDE.md so Claude reads AGENTS.md directly, or replace the sentence with an @AGENTS.md import.
• A CLAUDE.md symlinked to AGENTS.md: nothing to do, or delete the link. Either way the content is read once.
• A SessionStart hook that prints AGENTS.md: remove it. Once Claude reads AGENTS.md directly, the hook adds a second copy to the context.

If you want Claude-specific instructions on top of the shared file, the documented pattern is a CLAUDE.md that imports AGENTS.md first and adds its own sections below. Claude reads the imported file, then the rest:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

The alternative is a symlink:

ln -s AGENTS.md CLAUDE.md

We ran that in a scratch git repo: no output, and the link resolves. The docs flag two catches. First, Claude's Edit and Write tools refuse to write through a symlink and redirect Claude to edit AGENTS.md itself. Second, on Windows, Git checks a committed symlink out as a plain one-line text file unless core.symlinks is enabled, which leaves that clone with a broken CLAUDE.md. If anyone clones on Windows, use the import.

After you merge files, run /doctor prompt-audit (2.1.283+). By default it covers CLAUDE.md, CLAUDE.local.md and AGENTS.md files, looks for contradictions and stale references, and proposes edits without applying them until you ask. For what to actually write in the file, our guide on how to write a CLAUDE.md still applies - its advice to put @AGENTS.md at the top is now one option rather than the only one.

Gotchas and limits#

1. A personal CLAUDE.local.md turns AGENTS.md off for you. Because CLAUDE.local.md counts for the check, adding one to keep your own uncommitted notes stops Claude from reading the team's AGENTS.md. Nothing warns you. Fix: set claude-md-and-agents-md in ~/.claude/settings.json.

2. InstructionsLoaded hooks do not fire for a directly read AGENTS.md. They do fire for an AGENTS.md that a CLAUDE.md imports or symlinks to. If you use InstructionsLoaded hooks to audit what reaches the model, keep the import.

3. --add-dir directories contribute no AGENTS.md. Even with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD set, an added directory's CLAUDE.md loads but its AGENTS.md does not.

4. External imports load silently or not at all. For an @path import pointing outside your working directory, a CLAUDE.md triggers an approval prompt. An AGENTS.md read through the setting loads the external file only if you already approved external imports for that project, with no prompt. This is also why it is worth treating a cloned repo's AGENTS.md as live input; see agent config files are executable supply chain.

5. Some subagents start without it. Per the subagents docs, the built-in Explore and Plan subagents start without CLAUDE.md files, and a custom subagent with omitClaudeMd starts without user, project and local CLAUDE.md. AGENTS.md loaded as project instructions follows the same rules. More on subagent context in our sub-agents guide.

6. Some sessions cannot load it at all. The docs list three cases where Claude reads CLAUDE.md only and Project instructions is missing from /config: versions before 2.1.277, after you disabled the built-in plugin with /plugin, and in some cases the first session after upgrading from 2.1.276 or earlier. The env-vars docs add that in a clean environment on every run, such as a CI container, every run counts as a first session for flag-gated features. Our recommendation, not a documented rule: in ephemeral CI containers, keep a CLAUDE.md with @AGENTS.md as belt and braces, since the import works regardless and never double-reads.

7. No override or local semantics. AGENTS.override.md and AGENTS.local.md are not read. For personal overrides in Claude Code, use CLAUDE.local.md plus claude-md-and-agents-md.

8. Size rules are CLAUDE.md rules. Claude Code loads a CLAUDE.md-style file of up to 4 MiB and skips a larger one, and the docs recommend under 200 lines per file. Imports help organize but do not save context, because imported files load at launch too. If you are about to lean on an existing AGENTS.md, it is worth checking it against the six smells in our AGENTS.md configuration smells catalog, and setting expectations with the context-files ablation study.

How it compares to Codex's AGENTS.md loader#

Codex reads AGENTS.md natively and has the most detailed public discovery rules, so it is the closest comparison. Both rows below come from each tool's own docs: the Claude Code memory docs and the Codex AGENTS.md guide.

Each design has clear strengths. Codex's precedence is explicit and easy to reason about: one file per directory, concatenated root-down, with a predictable byte budget and an override file for temporary changes. Claude Code's strengths are the mode picker, import dedupe, and lazy subdirectory loading, which keeps a large monorepo's nested files out of context until they are relevant.

The AGENTS.md spec site, now stewarded by the Agentic AI Foundation under the Linux Foundation, says the closest AGENTS.md to the edited file wins and explicit chat prompts override everything. Both tools approximate "nearest wins" by ordering files root-first, so deeper files appear later in the prompt.

%% title: One AGENTS.md shared across agents
flowchart TD
  A[AGENTS.md - shared rules] --> CX[Codex reads natively]
  A --> CC[Claude Code reads it when no CLAUDE.md]
  A --> I["CLAUDE.md with @AGENTS.md import"]
  I --> CC2[Claude Code plus Claude-only rules]

Which setup should you pick#

• One AGENTS.md, no Claude-specific rules, everyone on 2.1.281+: delete CLAUDE.md and use the default mode.
• Claude-specific rules on top of shared ones: a CLAUDE.md with @AGENTS.md at the top. It works on every version, keeps InstructionsLoaded hooks firing, and lives in the repo.
• You personally keep a CLAUDE.local.md: set claude-md-and-agents-md in ~/.claude/settings.json.
• Mixed fleet with older versions, ephemeral CI, or plugin-disabled sessions: keep the import. It costs one line and never double-reads.

FAQ#

Does Claude Code read AGENTS.md if I also have a CLAUDE.md?#

Not by default. With a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above, only CLAUDE.md files load. To get both, set Project instructions to claude-md-and-agents-md or add @AGENTS.md to the CLAUDE.md.

Which Claude Code version do I need?#

Version 2.1.277 at minimum. Use 2.1.281 or later on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, an LLM gateway, or with telemetry disabled, and 2.1.285 or later to use the cc-plugin-agents-md@builtin settings key.

Can I commit the Project instructions mode to my repo?#

No. The setting is read from ~/.claude/settings.json, a --settings file, or managed settings, and ignored in project and local settings files. To make the behavior travel with the repo, commit a CLAUDE.md that imports @AGENTS.md.

Does Claude Code support AGENTS.override.md like Codex?#

No. Claude Code does not read AGENTS.override.md, AGENTS.local.md, or anything under .agents/. Use CLAUDE.local.md with claude-md-and-agents-md for personal overrides.

How do I confirm AGENTS.md loaded?#

Look for the no CLAUDE.md found; AGENTS.md loaded line at session start, run /memory and look for the path, or run /context and check Memory files. The last two need 2.1.280 or later.

Sources#

• Claude Code docs, memory and AGENTS.md: https://code.claude.com/docs/en/memory#agents-md
• Claude Code docs, glossary: https://code.claude.com/docs/en/glossary
• Claude Code docs, first session after an install or upgrade: https://code.claude.com/docs/en/env-vars#first-session-after-an-install-or-upgrade
• Claude Code docs, subagents: https://code.claude.com/docs/en/sub-agents
• Claude Code changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
• agents-md built-in plugin source: https://github.com/anthropics/claude-code/tree/main/mods/agents-md
• npm package and release dates: https://www.npmjs.com/package/@anthropic-ai/claude-code
• Codex AGENTS.md guide: https://developers.openai.com/codex/guides/agents-md
• AGENTS.md format: https://agents.md/

Continue Reading#

• How to Write a CLAUDE.md: The Complete 2026 Guide - what to put in the file now that Claude Code can read AGENTS.md directly
• AGENTS.md Configuration Smells: 91% of Popular Repos Get One of Six Wrong - fix the file before you rely on it
• Agent Config Files Are Executable Supply Chain - why an auto-loaded AGENTS.md in a cloned repo deserves review
• Which Coding Agent Reads Which Instruction File - CLAUDE.md, AGENTS.md, GEMINI.md and rules directories across Codex, Cursor, Copilot and the rest, from official docs