AGENTS.md vs CLAUDE.md: Which File Each Agent Reads
AGENTS.md vs CLAUDE.md: which file Claude Code and Codex read, the load order of each, and how to keep one shared file with an @AGENTS.md import or a symlink.
Josh Pocock7 min read
AI Coding
AGENTS.md vs CLAUDE.md
Stride AI Academy
AGENTS.md and CLAUDE.md do the same job: they're markdown files of project instructions that a coding agent loads at the start of every session. The difference is who reads them. Codex reads AGENTS.md. Claude Code reads CLAUDE.md, and since v2.1.277 it also reads AGENTS.md, but only when there's no CLAUDE.md in your project. To keep one shared file, write your rules in AGENTS.md and add a CLAUDE.md that contains the line @AGENTS.md.
This guide covers which tool reads which file, how each one finds and orders them, the two ways to share one source of truth, and how to check what loaded. Everything here was checked against Claude Code's memory docs and OpenAI's Codex AGENTS.md guide on November 22, 2026.
AGENTS.md vs CLAUDE.md at a glance
| Claude Code | Codex | |
|---|---|---|
| Main file | CLAUDE.md |
AGENTS.md |
| Reads the other file? | Reads AGENTS.md when you have no CLAUDE.md |
Only if you list another name as a fallback |
| Personal file | ~/.claude/CLAUDE.md |
~/.codex/AGENTS.md |
| Local override | CLAUDE.local.md, gitignored |
AGENTS.override.md |
| Imports other files | Yes, @path |
Not documented |
| Size guidance | Under 200 lines per file | Stops at 32 KiB combined by default |
Which files Claude Code reads
Claude Code loads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it, plus your personal ~/.claude/CLAUDE.md. The memory docs say the files are joined rather than overriding each other, with files nearer your working directory read last. Files in subdirectories load when Claude works on files there.
When Claude Code reads AGENTS.md
The memory docs give this table of defaults:
| What's in your repo | What Claude reads |
|---|---|
AGENTS.md, and no CLAUDE.md or CLAUDE.local.md in your folder or above |
Your AGENTS.md |
AGENTS.md and a CLAUDE.md or CLAUDE.local.md |
Your CLAUDE.md files only |
A CLAUDE.md that imports AGENTS.md |
Your CLAUDE.md, with AGENTS.md included through the import |
Two details catch people out:
CLAUDE.local.mdcounts. Adding a personalCLAUDE.local.mdto a repo that relies onAGENTS.mdstops Claude readingAGENTS.md.- Your user file doesn't count.
~/.claude/CLAUDE.md, a managedCLAUDE.mdand.claude/rules/files keep loading alongsideAGENTS.md.
Reading AGENTS.md directly needs Claude Code v2.1.277 or later. The docs also list sessions that can't read it, such as one where you've turned off the built-in plugin that reads it. In those, import it from a CLAUDE.md.
Change which files Claude Code loads
Type /config and set Project instructions to one of these:
| Value | What Claude reads |
|---|---|
claude-md-or-agents-md |
CLAUDE.md, or AGENTS.md if there's no CLAUDE.md. The default |
claude-md-and-agents-md |
Both, each folder's CLAUDE.md first |
claude-md |
CLAUDE.md only |
managed-only |
Only your organization's managed CLAUDE.md and auto memory |
Which files Codex reads
OpenAI's guide describes two levels:
- Global. Codex looks in its home folder,
~/.codexby default. It usesAGENTS.override.mdif present, otherwiseAGENTS.md. - Project. Codex starts at the project root, usually the Git root, and walks down to your current folder. In each folder it checks
AGENTS.override.md, thenAGENTS.md, then any fallback names you set, and uses at most one file per folder.
Files are joined root first, so instructions closer to your current folder come later and override earlier ones. Empty files are skipped. Codex stops adding files once the total reaches project_doc_max_bytes, which defaults to 32 KiB.
Both settings live in ~/.codex/config.toml. The guide's example:
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536Restart Codex after changing it. Our Codex config.toml guide covers the rest of that file, and the Codex CLI tutorial covers setup.
The guide's fallback examples don't mention CLAUDE.md. A fallback name is only checked in a folder that has no AGENTS.md, so if your repo already has an AGENTS.md, Codex reads that.
How to keep one shared file
If you use both tools, you don't want two copies of the same rules drifting apart. The memory docs give two ways to keep AGENTS.md as the single source.
Option 1: import AGENTS.md from CLAUDE.md
Put your shared rules in AGENTS.md. Then create a CLAUDE.md next to it:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.Claude reads the imported file first, then anything below the import. That gives you a place for Claude-only notes without touching the shared file. The docs say keeping the import never makes Claude read AGENTS.md twice, whichever Project instructions value you choose.
This is the setup our site owner runs in every repo: shared agent instructions in AGENTS.md, and a CLAUDE.md that imports it with the line @AGENTS.md. Codex reads AGENTS.md directly, and Claude Code gets the same content through the import.
A few import rules from the memory docs:
- Relative paths resolve from the file that contains the import.
- Imports can nest up to four hops deep.
- An import inside backticks, like
`@README`, stays literal text. - Imported files load with the file that imports them, so they still count against your context.
Option 2: symlink CLAUDE.md to AGENTS.md
If you don't need any Claude-only content, the docs say a symlink also works:
ln -s AGENTS.md CLAUDE.mdCheck two constraints first. Claude's Edit and Write tools won't write through a symlink, so edits go to AGENTS.md directly. And the docs advise using the import instead if anyone on the project works on Windows. Creating a symlink there needs Administrator rights or Developer Mode, and Git checks out a committed symlink as a plain one-line text file unless core.symlinks is on.
Which should you pick?
Use the import. It works on every operating system, it leaves room for Claude-only instructions, and the docs confirm it never double-loads. Use a symlink only on a Mac or Linux team with nothing Claude-specific to add.
How to check what loaded
In Claude Code, run /memory and look for the file's path in the list, or run:
/context alland confirm CLAUDE.md appears under Memory files. When Claude reads AGENTS.md directly, the docs say an interactive session shows a line such as no CLAUDE.md found; AGENTS.md loaded.
In Codex, OpenAI's guide suggests asking it from the repo root:
codex --ask-for-approval never "Summarize the current instructions."For a nested folder, add --cd services/payments and ask it to list the instruction sources it loaded.
What to put in the shared file
The same advice applies to both files. Anthropic's guidance says the file works best when it holds only what an agent can't work out from the code:
- The exact install, test, typecheck and lint commands
- Places where the code is misleading
- Decisions that aren't written down in the repo
- Anything you've had to correct twice
A short shared file looks like this:
# Commands
- Install: pnpm install
- Test one file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit
# Conventions
- Use the error helpers in src/lib/errors.ts
- Never edit generated files in src/gen/
# Before you finish
- Run the typecheck and the tests for any file you changedKeep tool-specific settings out of it. Claude Code permissions belong in .claude/settings.json, and Codex settings belong in config.toml. For longer starter files, see CLAUDE.md file examples, and for how the two agents compare beyond their instruction files, Claude Code vs Codex.
Moving from AGENTS.md to CLAUDE.md the other way
If you'd rather end up with a separate CLAUDE.md, the memory docs say /import appends a one-time copy of files such as AGENTS.md to the matching CLAUDE.md. After that the two files are independent, so you'd maintain both.
Learn to build with Claude Code
The Stride AI Coding course teaches Claude Code and Codex for building client tools, written for non-programmers, with weekly live calls to review your builds. Many of the free guides cover Claude Code setups, and the Claude Code community is where members compare theirs.
FAQ
What is the difference between AGENTS.md and CLAUDE.md?
Both hold project instructions an agent loads every session. Codex reads AGENTS.md. Claude Code reads CLAUDE.md, and reads AGENTS.md only when there's no CLAUDE.md in your project, on v2.1.277 or later.
Does Claude Code read AGENTS.md?
Yes, on v2.1.277 or later, when there's no CLAUDE.md or CLAUDE.local.md in your working directory or above it. To read both, set Project instructions to claude-md-and-agents-md in /config, or import it with @AGENTS.md.
Does Codex read CLAUDE.md?
Not by default. OpenAI's guide says Codex checks AGENTS.override.md, then AGENTS.md, then any names in project_doc_fallback_filenames. A fallback name is only used in a folder with no AGENTS.md.
How do I use one file for both Claude Code and Codex?
Write your rules in AGENTS.md, then add a CLAUDE.md containing @AGENTS.md. Codex reads AGENTS.md directly, and Claude Code reads it through the import. Add Claude-only notes below the import line.
Should I symlink CLAUDE.md to AGENTS.md?
Only if nobody on the project uses Windows and you have nothing Claude-specific to add. Anthropic's docs recommend the import on Windows, where symlinks need extra permissions and can check out as plain text files.
How do I check which instruction file loaded?
In Claude Code, run /memory or /context all and look for the file. In Codex, ask it from the repo root to summarize the current instructions or list the sources it loaded.