Claude Code 2.1.277 adds support for AGENTS.md

The commit page is raw HTML. I have the key facts I need from the OG description: the commit title is mods/agents-md: the AGENTS.md project-instructions mod (#95409), and the commit description mentions mods/types: refresh the engine typings, mods/agents-md: the AGENTS.md project-instructions mod, and mods/agents-md: the instructionFiles option.

Let me get a few more lines of the plugin.json to understand the instructionFiles option values: I now have all the concrete facts I need. The source is a thin announcement commit, so the article will focus on the mechanism, the four modes, the instructionFiles option, and what builders need to verify. Here's the article:

Let me get a few more lines of the plugin.json to understand the instructionFiles option values: I now have all the concrete facts I need. The source is a thin announcement commit, so the article will focus on the mechanism, the four modes, the instructionFiles option, and what builders need to verify. Here's the article:

Anthropic shipped version 2.1.277 of Claude Code with a new built-in mod called agents-md, adding native support for AGENTS.md project-instruction files — the convention popularized by OpenAI's Codex CLI — directly alongside or in place of Claude Code's own CLAUDE.md files. The change arrives as PR #95409 in the anthropics/claude-code repository, merged into the binary as a first-party mod alongside the three existing built-ins: sec-default, diff, and telemetry.

This article covers exactly what agents-md does, what four operating modes it exposes via the instructionFiles option, how a team should update their installation, and what to watch for in subsequent releases. It is written for developers who maintain shared codebases with multiple AI coding agents and who need one instruction file to be respected regardless of which tool picks up the session.

01What shipped

The agents-md mod ships as a complete plugin package — mods/agents-md/.claude-plugin/plugin.json, a hooks/hooks.json entry, and TypeScript under mods/agents-md/hooks/ — and is compiled into the Claude Code binary the same way diff and telemetry are. The mods/README.md now lists four built-in mods, up from three, with agents-md described as: "AGENTS.md as project instructions, by one option: loaded where the project has no CLAUDE.md of its own, or beside it, placed and framed exactly as the engine places CLAUDE.md, nested ones on a Read."

The commit also includes mods/types: refresh the engine typings, which updates the type surface the mod system exposes to hook authors. The diff's old-files fixture had a naming issue (isLink) corrected in the same squash. Neither of those changes is user-visible, but they indicate the engine's internal plugin API is being hardened ahead of broader external plugin support.

02What improved

The agents-md mod exposes a single user-configurable key, instructionFiles, with four string values that control how AGENTS.md and CLAUDE.md coexist in the same repository. Teams that previously had to maintain two separate instruction files — one for each agent CLI — can now consolidate.

03What you gain

Teams running both Claude Code and another agent CLI — such as OpenAI Codex CLI or any tool that reads AGENTS.md — no longer need to duplicate their project instructions. Under the default claude-md-or-agents-md mode, a repository that ships only an AGENTS.md gets those instructions loaded by Claude Code as if they were a CLAUDE.md: rendered, announced, and withheld from sub-agents exactly as the engine handles its own file. A prompt.context hook asks $.fs.ancestors for every AGENTS.md and .claude/AGENTS.md from the filesystem root to the working directory; a tool.call hook on Read attaches any nested ones found under the project root.

For organizations with managed settings, the managed-only mode is a direct replacement for any ad-hoc hook logic that previously stripped user-level instructions. Telemetry hooks within agents-md emit load and mode events — load-event, mode-event, nested-event — through the existing $.telemetry interface, so analytics dashboards that already track Claude Code session events will see agents-md load counts without additional configuration.

04How to get it

Update to 2.1.277 or later with the standard commands. The current published version on npm is 2.1.283, so an update will bring you past 2.1.277 to the latest available release:

```bash
# If you installed via npm
npm install -g @anthropic-ai/claude-code

05Or use the built-in update command

The agents-md mod is built in and active by default after the update. No flag is needed to opt in for the default claude-md-or-agents-md mode. To switch mode, set instructionFiles in your Claude Code user config or in the managed settings your organization deploys:

```bash
# Check current version after update
claude --version

06Set in ~/.claude/config.json → instructionFiles: "claude-md-and-agents-md"

```

Verify the mod is running by opening a project that has only an AGENTS.md and no CLAUDE.md, starting a session, and checking the session transcript for the instruction-load announcement Claude Code emits at context initialization.

07What to watch next

The current plugin version is 0.1.0, which signals that the instructionFiles option schema is not yet frozen. Anthropic may add or rename values before marking it stable, so teams that pin managed-only or claude-md-and-agents-md in organization-managed settings should monitor the changelog between minor releases. The 2.1.x series has been shipping rapidly — 2.1.278 through 2.1.283 followed within days — and each point release can modify built-in mod behaviour without a separate opt-in.

The telemetry surface is worth watching independently. The agents-md mod logs load-counts, mode-choice, and nested events through the same $.telemetry interface that telemetry mod introduced; any tooling that parses Claude Code telemetry output will start receiving new event types after the update. Teams with strict telemetry parsers should verify those parsers handle unexpected keys gracefully before deploying 2.1.277 or later into shared CI environments.