Claude Code reads AGENTS.md as of version 2.1.277, but only when a project has no CLAUDE.md
The format came out of OpenAI's Codex and the Linux Foundation stewards it now, and the agents.md page still doesn't name Claude Code among the tools that read it.
Claude Code shipped version 2.1.277 on September 18, 2026, and the first line of its release notes is about a file Anthropic didn't invent. In a project with no CLAUDE.md, Claude Code now reads AGENTS.md instead.
AGENTS.md is plain Markdown at the root of a repository, holding the build steps, tests and conventions a coding agent needs but a human contributor doesn't. Codex from OpenAI reads one. So do Cursor and Gemini CLI.
- Version
- Claude Code 2.1.277
- Released
- 2026-09-18
- Default
- Only when the project has no CLAUDE.md
- Steward
- The Agentic AI Foundation, under the Linux Foundation
- On GitHub
- 60k+ examples
When it actually reads the file
The default is narrow. Anthropic's documentation sets out three cases, and one of them loads AGENTS.md: a repository that has an AGENTS.md and no CLAUDE.md or CLAUDE.local.md in the working directory or above it. Put a CLAUDE.md back and Claude Code reads that alone.
By default, Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it.
A CLAUDE.local.md counts for that check, which is the part I'd have got wrong. Keeping your own uncommitted notes in a project that runs on AGENTS.md (sandbox URLs, preferred test data, the usual) stops Claude from reading the shared file for you.
Turns out you can change it. Typing /config opens a Project instructions setting with four values, and claude-md-and-agents-md loads both, each directory's CLAUDE.md first and its AGENTS.md after them.
Where the format came from
AGENTS.md emerged from work across several tools, among them OpenAI's Codex, Jules from Google and Cursor, and the Agentic AI Foundation under the Linux Foundation stewards it now. GitHub carries more than 60,000 examples of the file, and agents.md says the main OpenAI repository alone has 88 of them.
That site keeps a list of the agents its format works with: Codex, Jules, Factory, Aider, Zed, Warp, Cursor, Gemini CLI, Devin, Windsurf, the coding agent in GitHub Copilot. Claude Code isn't on it.
Rather than introducing another proprietary file, we chose a name and format that could work for anyone
Where it won't work
Reading AGENTS.md directly needs 2.1.277 or later, and Anthropic's docs name sessions where it can't happen at all: ones running on Amazon Bedrock, or with telemetry disabled. The fix there is an @AGENTS.md import inside a CLAUDE.md, or a symlink from CLAUDE.md to the file.
Symlinks behave differently on Windows. Git checks a committed one out as a plain text file unless core.symlinks is enabled, which leaves that clone with a one-line CLAUDE.md where the project's instructions should be, so Anthropic tells Windows users to use the import.