Claude Code 2.1.277 reads AGENTS.md natively: one instruction file across coding agents

News from the agent-tooling ecosystem just outside OpenAI's own: Anthropic's coding agent Claude Code added AGENTS.md support in version 2.1.277 — the project-instruction format that OpenAI's Codex ecosystem has standardized on. This article only restates what can be verified: the official CHANGELOG entry, the mods/agents-md README (re-fetched and checked item by item on 2026-09-22), npm registry timestamps, and the format description on the official agents.md site. Questions like "why did the two ecosystems converge" have no source, so we leave them alone.

1. What happened: the official entry and the timeline

The CHANGELOG.md entry for 2.1.277 is a single 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)

The timeline (verified 2026-09-22):

• 2026-09-18: PR #95409 ("mods/agents-md: the AGENTS.md project-instructions mod") lands in the anthropics/claude-code repo, with a same-day follow-up fix in #95417;
• 2026-09-18T16:22Z: @anthropic-ai/claude-code 2.1.277 publishes to npm (registry timestamp);
• 2026-09-19T01:48Z: 2.1.278 publishes, with no further AGENTS.md entries. As of 2026-09-22, npm's latest and next dist-tags both point at 2.1.278, while the stable tag still sits at 2.1.267 — installs pinned to the stable channel do not get this feature yet.

2. AGENTS.md: an open instruction format that crosses tools

The official agents.md site positions the format in one line: a README for agents — README.md files are for humans, AGENTS.md gives AI coding agents the build steps, test commands, and conventions they need. The site says the format is used by over 60k open-source projects and lists its adopters: OpenAI Codex, Google Jules, Aider, goose, Zed, Warp, VS Code, Devin, Cursor, Gemini CLI, GitHub Copilot's coding agent, Windsurf, and more.

In our earlier tool comparisons, AGENTS.md was the Codex CLI collaboration hook: write it at the repo root, and Codex picks it up. Claude Code's counterpart was its own CLAUDE.md. After 2.1.277, that picture has changed — here is exactly how.

3. The implementation: a built-in plugin named agents-md, with four modes

The notable implementation detail: AGENTS.md support is not a new parser hard-wired into the engine. It is a built-in plugin (officially a "mod") whose code lives in the repo's mods/agents-md directory. The README's first sentence is the essence: AGENTS.md is read the way Claude Code reads CLAUDE.md, as a plugin, under one option — instructionFiles.

The four values:

4. The default mode's fallback test: when it reads, and when it stands down

The default mode deserves its own section, because the real rule is finer than "no CLAUDE.md means AGENTS.md."

The test reads what the engine actually loaded for the context: a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in any directory from the root down to the working directory means the project has instruction files of its own — the plugin stays out entirely. Four kinds of files do not count: the organization's managed file, the person's ~/.claude/CLAUDE.md, a .claude/rules file, and a CLAUDE.md added through an extra --add-dir directory (the nested walk does not see them anyway).

When the test comes up empty, every AGENTS.md and .claude/AGENTS.md on that path joins the instruction files the engine renders; from then on, a Read under a subdirectory attaches that directory's AGENTS.md — unless a CLAUDE.md in the same directory claims it.

5. How files reach the context, and the nested rules

The README draws one boundary explicitly: how the files reach the model is the engine's doing, not the plugin's. The mechanism is the prompt.context hook: the engine hands the hook the instruction files behind claudeMd (each with path, kind, content, and an optional parent; kinds are managed / user / project / local / memory, in load order), the hook answers with the changed list, and the engine renders claudeMd from the answered files with its own preamble and framing and announces them by name.

That means a plugin-added AGENTS.md carries the project kind — to everything downstream it is a project instruction file: same place in the context, same framing, same omission rules (Explore, Plan, and custom agents with omitClaudeMd still get managed files only). If an organization prepends its own plugin on prompt.context, it has the last word on the files.

Nested rules: when the Read tool reads a file, the plugin walks only the directories strictly between the project root and the read file, attaching any AGENTS.md there that this agent loop has not yet been given, that is not among the context's instruction files (by path or by text), and that no CLAUDE.md of the same directory claims. Attachments land after the tool result, framed byte for byte like the engine frames a nested CLAUDE.md (Contents of <path>:); each file attaches once per loop and conversation, and a compaction or /clear restarts the count. A moved project root (/cd, a host directory change, worktree moves) is followed live, and the fallback decision and attachments start over.

6. The eight documented gaps vs CLAUDE.md

The README devotes a section to how AGENTS.md differs from CLAUDE.md under the loading modes (default and both), naming the loader fact each gap stems from:

1. Nested files attach on a text Read only; the engine also attaches a directory's CLAUDE.md for a file @-mentioned in the prompt, for the IDE's opened file or selection, and for the Read tool's notebook, image, and PDF results — the plugin triggers on none of these;
2. A plugin-attached nested file is not registered in the loop's read-file state: after a compaction the engine does not restore it among recently read files (the plugin re-attaches at the next Read), and a mid-session change to it is not re-announced;
3. /cd carries the new tree's CLAUDE.md in its own notice; the plugin's files for the new tree arrive in the same next request through the engine's instructions announcement;
4. Paths compare by spelling, while the engine resolves a symlinked alias of the working directory before deciding a file is inside it;
5. --add-dir directories contribute no AGENTS.md, where the engine can load their CLAUDE.md;
6. /memory and the # shortcut do not know AGENTS.md files, and the engine's own initial-load row does not count them (the plugin's agents_md_load row does);
7. An @ import outside the working directory inside an AGENTS.md is honoured only after the approval the engine asks for a CLAUDE.md's external imports has been given (without it the import is left out); the approval dialog itself is raised for CLAUDE.md imports alone;
8. A non-fork subagent gets a nested AGENTS.md at its own first Read under a directory even when the parent's loop was already given it; the engine does not hand such a subagent the nested CLAUDE.md again. A fork matches the engine on both sides.

7. Configuration, legacy-key compatibility, and platform limits

As a built-in, its configuration surface is the Project instructions row in /config — a picker over the four values, each described there. The hand-written equivalent is the following, placed in user settings (~/.claude/settings.json), a --settings file, or managed settings (a project's .claude/settings.json is not read for plugin options):

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

Changing it reloads the module, and the next context the engine builds (the next turn after the reload, a new conversation, /clear, or a compaction) carries the new mode's files. A hand-typed value outside the four is flagged once in the transcript and then reads as the default.

Legacy-key compatibility: the option was first keyed projectInstructions, with the values claude, agents-fallback, both and none. A value stored under that key is honored through a fixed mapping — none as managed-only, claude as claude-md, agents-fallback as the default mode, both as both-modes, and any other value as claude-md (which adds nothing and never equals the default — unlike an invalid value under the new key, which reads as the default). The first session.start of a load says in the transcript how the old key was read; once instructionFiles is set to anything but its default, the old key is not read and the transcript says to remove it.

Platform limits: the changelog says, verbatim, not yet on Bedrock, Vertex or Foundry. Also, in runs where the engine loads no instruction files at all (--bare without --add-dir, --safe-mode, or CLAUDE_CODE_DISABLE_CLAUDE_MDS set), the plugin's walk finds none and adds none — CLAUDE.md and AGENTS.md alike.

8. Observability, telemetry, and tests

The plugin logs counts and closed choices only — no paths, no file text — and everything goes through the telemetry plugin's noun (where that plugin is not seated, the calls are dropped without a trace): agents_md_mode once per fresh load (mode and whether the session is interactive); agents_md_load on the first context under the default and both modes (files handed to the engine, their @ imports, total content length, whether the plugin yielded to the project's own CLAUDE.md, and whether the walk failed), plus one agents_md feature mark; agents_md_nested whenever a Read attaches nested files.

The test entry point is claude plugin test mods/agents-md. The bundled tests cover four default-mode scenes: a project with AGENTS.md alone gets it as a project instruction file plus one transcript line naming it; a project with its own CLAUDE.md is left to the engine without a walk; a failed walk leaves the context as handed; and session start goes on untouched whether or not a telemetry provider is seated.

9. What it means for Codex users (our observation)

The following is our reading of the verifiable facts above, not an official statement:

• One file, two ecosystems. Codex — already on the official adopter list — and Claude Code are the flagships of the two largest CLI coding-agent ecosystems. A single AGENTS.md in a repo now serves both; our August comparison piece listed AGENTS.md as a Codex differentiator, and that claim needs a "Claude Code reads it too" footnote as of 2026-09-18.
• The format is unchanged; the loading semantics are per-tool. AGENTS.md is still the README for agents. The fallback test, nested attachment, and the eight gaps above are Claude Code's implementation semantics. How Codex reads the same file is a matter for Codex's own docs — this article does not compare loading details across tools.
• On the configuration side, the default leans non-intrusive: existing projects with a CLAUDE.md change nothing; only teams who want AGENTS.md unconditionally need to touch /config.

10. Common issues and troubleshooting

• AGENTS.md seems ignored: check whether the project has a CLAUDE.md of its own (including .claude/CLAUDE.md and CLAUDE.local.md) — under the default mode the plugin stands down; make sure a new context has been built since the change (the turn after a reload, or a new session); and rule out runs where the engine loads no instruction files at all (--bare / --safe-mode / CLAUDE_CODE_DISABLE_CLAUDE_MDS).
• Config in the project's .claude/settings.json does nothing: plugin options are not read from project-level settings; put them in user settings, --settings, or managed settings.
• A nested AGENTS.md never attaches: the trigger is the Read tool reading a file in that directory as text; @-mentions, IDE-opened files, and notebook / image / PDF reads do not trigger it (gap #1); a CLAUDE.md in the same directory wins.
• A transcript line about how the old key was read: a projectInstructions value is still stored; interpret it via the mapping in section 7, and once you set the new key to a non-default value, delete the old one.
• The feature is missing on the stable channel: as of 2026-09-22, npm's stable dist-tag sits at 2.1.267 and latest at 2.1.278; the feature ships in 2.1.277.

11. Next steps

• Codex CLI vs Cursor vs Aider vs Claude Code: 2026 AI coding tools compared — the broader tool landscape AGENTS.md lives in, with git/CI fitness per tool;
• Getting started with OpenAI Codex CLI: from install to daily use — how the Codex side uses project instructions and worktree workflows;
• GPT-6-Astra Goes Live: Codex Model Picker and Amazon Bedrock Catalogs — the latest changes on the Codex model surface.