What is the difference between CLAUDE.md and AGENTS.md?

CLAUDE.md is the instruction file Anthropic's Claude Code loads at the start of every session, while AGENTS.md is an open Markdown format for any coding agent, read natively by OpenAI Codex and Cursor and, according to agents.md, used by over 60k open-source projects. Both are plain Markdown that the tool adds to the model's context; Claude Code's docs call CLAUDE.md "context, not enforced configuration". The real differences are which tools read each file, how overrides work, and which file wins when a repository has both. Since v2.1.277, Claude Code reads AGENTS.md too, but by default only when no CLAUDE.md is present.

Which coding tools read CLAUDE.md and which read AGENTS.md?

Each tool's own documentation gives a different answer, so check the tool, not the file name:

Tool	Reads AGENTS.md	Reads CLAUDE.md	Where it looks
Claude Code	Yes, from v2.1.277, by default only when no CLAUDE.md or CLAUDE.local.md is in the working directory or above	Yes	~/.claude/CLAUDE.md, ./CLAUDE.md or ./.claude/CLAUDE.md, ./CLAUDE.local.md, plus a managed policy file
OpenAI Codex	Yes	Not by default; Codex ignores file names that are not on its list	~/.codex/AGENTS.md, then each directory from the project root down to your current directory
Cursor	Yes, in the project root and subdirectories	Yes, "the same way it reads AGENTS.md", applied to every conversation	Project root and subdirectories

The AGENTS.md format has no required fields. It is stewarded by the Agentic AI Foundation under the Linux Foundation.

Which file wins when a repository has both?

In Claude Code, the default Project instructions value is claude-md-or-agents-md: if a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in your working directory or above it, Claude Code reads the CLAUDE.md files only. Set the value to claude-md-and-agents-md in /config to load both, CLAUDE.md first. Claude Code does not read AGENTS.override.md, AGENTS.local.md or anything under .agents/.

In OpenAI Codex, each directory contributes at most one file, checked in the order AGENTS.override.md, AGENTS.md, then any names in project_doc_fallback_filenames. Codex joins them from the root down, so files closer to your working directory override earlier ones, and it stops at 32 KiB (project_doc_max_bytes) by default.

In Cursor, nested AGENTS.md files combine with their parents, and the more specific file takes precedence.

How do you keep one instruction file for every tool?

Keep AGENTS.md as the shared file and point Claude Code at it. These steps follow the Claude Code and Codex docs:

1. Put build commands, test commands and conventions in AGENTS.md at the repository root. Codex and Cursor read it directly.
2. If you need Claude-specific lines, create a CLAUDE.md next to it that starts with @AGENTS.md, then add the Claude-only instructions below. Claude Code reads the imported file first and does not load it twice.
3. If you have no Claude-specific content, ln -s AGENTS.md CLAUDE.md also works, but Claude Code's docs advise the import instead when anyone clones the repository on Windows.
4. Run /context or /memory in Claude Code to confirm the file loaded. In Codex, ask "Summarize the current instructions." and check that it quotes your AGENTS.md.

Cursor also reads CLAUDE.md, so Claude-only lines reach Cursor's Agent as well. Keep them tool-neutral where you can.

When is a shared instruction file not enough?

A shared AGENTS.md is enough when one person or a small team needs the same commands and conventions in every tool. It is still static text: each tool loads it when a session starts, whatever the task, and it does not collect what agents learn. That learning stays inside each tool, for example in Claude Code's machine-local auto memory, covered in How does Claude Code memory work?.

elephant.broker is a pluggable runtime for AI agents that connects to Claude Code, Codex, Cursor or your own harness through an MCP server, native plugins or a REST API. On every turn, elephant.broker places versioned procedures for the task at hand and writes decisions and corrections back for the next turn. For the cross-tool setup, see Can Claude Code, Codex and Cursor share one memory?

Sources

• Anthropic, Claude Code: How Claude remembers your project
• OpenAI, Codex: Custom instructions with AGENTS.md
• Cursor: Rules reference, Rules help
• AGENTS.md: agents.md
• elephant.broker: overview, how a turn flows

Product details come from each vendor's public documentation as viewed on 2026-10-23 and may have changed. Product names are trademarks of their respective owners; elephant.broker is not affiliated with them.