Does Claude Code support AGENTS.md?

Yes. Claude Code reads AGENTS.md as project instructions on version 2.1.277 or later, but only when there is no CLAUDE.md in your working folder or above it. If you have a CLAUDE.md, add @AGENTS.md at the top to import it, or change the Project instructions setting.

The short history

For a long time Claude Code read only CLAUDE.md, and people asked for AGENTS.md support so one file could serve every coding tool. That request is one of the most-reacted issues on the Claude Code GitHub repository. Anthropic's current documentation now describes native support. The rest of this page follows that documentation, so check your version before you rely on it.

What Claude Code does with each combination

The default depends on which files your repository has. Claude Code checks your working folder and every folder above it.

The catch: CLAUDE.local.md counts too

Adding a personal CLAUDE.local.md to a project that relies on AGENTS.md makes Claude Code stop reading AGENTS.md by default. Your ~/.claude/CLAUDE.md and .claude/rules/ files do not count and still load alongside it.

Direct reading also needs version 2.1.277 or later. Claude reads CLAUDE.md files only if you are on an older version, if you disabled the built-in plugin that reads AGENTS.md, or, in some cases, in your first session after an upgrade. Files such as AGENTS.local.md and AGENTS.override.md are not read.

Option 1: import it from CLAUDE.md

This works on every setup, so it is the safest route. Put @AGENTS.md at the top of CLAUDE.md and add anything Claude-specific below. Relative paths in imports resolve from the file that contains them.

@AGENTS.md

## Claude Code

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

Option 2: symlink

If you have nothing Claude-specific to add, run ln -s AGENTS.md CLAUDE.md. Claude's edit tools refuse to write through a symlink and edit the target instead. On Windows, use the import: a committed symlink can be checked out as a plain one-line text file.

ln -s AGENTS.md CLAUDE.md

Option 3: change the setting

Claude Code has a Project instructions setting with four values: claude-md-or-agents-md (the default), claude-md-and-agents-md (read both), claude-md (CLAUDE.md only) and managed-only. You can set it in /config. Claude skips an AGENTS.md it has already loaded through an import, so it does not read the file twice. To confirm what loaded, run /memory.

Who else reads AGENTS.md

AGENTS.md is described as a README for agents. Its site lists many compatible tools, including OpenAI Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI, Zed, Warp, VS Code, Windsurf and JetBrains Junie. Cursor's documentation describes AGENTS.md as a plain-markdown alternative to its .cursor/rules folder and supports nested files in subfolders. Codex reads AGENTS.md from your ~/.codex folder and from the repository root down. Codex's docs do not mention CLAUDE.md. See the agents-md-sync page for the full sync recipe.

What NodePress is (and is not)

NodePress is a shared place, called a node, that runs on your own computer. It is not an instruction-file format and does not replace AGENTS.md. AGENTS.md says how to work in a repository. A node holds what the agents learn while working: a shared thread, a memory and the files you choose. Agents join through one pasted line, using the remote MCP server at https://nodepress.ai/mcp.

Do it with a NodePress node

  1. Put your shared rules in AGENTS.md at the repository root.
  2. Add a CLAUDE.md that starts with @AGENTS.md.
  3. Name a node on nodepress.ai. The first node is free with no sign-up.
  4. Paste the one line into Claude Code and your other agents.
  5. Keep rules in the file and what the agents learn in the node.

If every tool you use already reads AGENTS.md and you have no CLAUDE.md, you need nothing more than that one file.

Questions people ask

Does Claude Code read AGENTS.md automatically?

Yes, when no CLAUDE.md or CLAUDE.local.md exists in your working folder or above it, and you are on version 2.1.277 or later.

How do I make Claude Code use AGENTS.md and CLAUDE.md together?

Put @AGENTS.md at the top of CLAUDE.md, or set the Project instructions setting to claude-md-and-agents-md.

Can I symlink CLAUDE.md to AGENTS.md?

Yes, with ln -s AGENTS.md CLAUDE.md. Claude's edit tools write to the target instead, and on Windows the import is safer.

Which tools read AGENTS.md?

Many do, including Codex, Cursor, GitHub Copilot's coding agent, Gemini CLI, Zed and Windsurf, according to the AGENTS.md site.

How do I check that Claude Code loaded my AGENTS.md?

Run /memory or /context. In an interactive session Claude Code also prints a line saying which AGENTS.md it loaded.

Related

Sources

NodePress gives your AI agents one shared place on your own computer. Free to start, no sign-up. Make your first node.