CLAUDE.md vs AGENTS.md: the difference
CLAUDE.md is Anthropic's own instructions file, read only by Claude Code. AGENTS.md is a separate format built for Codex, with its own discovery rules and a hard size cap CLAUDE.md does not have.
Last verified 29 September 2026. Every priced or limited claim below links to its source.
Where does each file live?
CLAUDE.md is read by Claude Code from several locations at once: a managed policy file, ~/.claude/CLAUDE.md for the user, ./CLAUDE.md or ./.claude/CLAUDE.md for the project, and CLAUDE.local.md for a personal, gitignored copy, all concatenated together with no strict precedence order between them. source, checked 29 September 2026.
AGENTS.md is read by Codex starting at a global ~/.codex/AGENTS.md, then walking from the project root down to the current directory, checking AGENTS.override.md before AGENTS.md in each folder, and joining everything it finds from the root down. source, checked 29 September 2026.
Do the size limits differ?
CLAUDE.md has no hard byte cap, but Anthropic's own docs recommend keeping each file under roughly 200 lines, warning that longer files consume more context and reduce how reliably Claude follows them. source, checked 29 September 2026.
AGENTS.md has a hard cap: Codex stops adding files once their combined size reaches 32 KiB (32,768 bytes) by default, and content past that limit is silently truncated with no warning shown to the user. Real users have reported losing instructions this way without knowing why. source, checked 29 September 2026.
What goes in each file?
Both are meant to hold the same kind of thing: build and test commands, naming conventions, architecture in a few sentences, and hard constraints the agent should never break. Neither is meant to hold full API documentation or a changelog the agent can already read from the code itself.
Do you need both?
Only if you use both tools on the same project. Nothing keeps the two files in sync automatically: a correction you give Claude Code in CLAUDE.md has to be copied into AGENTS.md by hand if you also use Codex on the same repository. Mover OS's free templates come as a CLAUDE.md, an AGENTS.md and a GEMINI.md with the same content, so each tool reads the same plan. See the how to write CLAUDE.md and AGENTS.md guide for the step by step. The kit is not for anyone who uses one tool and keeps a short file by hand.
Common questions
Can I just use one file for both tools?
Each tool wants its own filename. Claude Code looks for CLAUDE.md by name and Codex looks for AGENTS.md by name; neither reads the other's filename automatically as of this check.
Which file should I write first?
Whichever tool you actually use. If you only run Claude Code, write CLAUDE.md and skip AGENTS.md entirely.
What happens if my AGENTS.md is too long?
Codex truncates it silently at 32 KiB with no error shown, so instructions near the end of a long file may simply never load. Split guidance across nested directory AGENTS.md files instead of one giant root file.
Know which file you need? The next guide covers what goes in it. Or Mover OS, $49 once. It is the wrong choice if you want something that keeps running while your computer is off.