AGENTS.md vs CLAUDE.md: which file each agent reads

AGENTS.md is the open, tool-neutral instructions file that Codex reads; CLAUDE.md is Claude Code's own. Claude Code v2.1.277 and later also reads AGENTS.md, but by default only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working directory or above it. If both tools work on a repository, put the shared instructions in AGENTS.md and either have no CLAUDE.md at all or one whose first line is @AGENTS.md.

How the two files compare

Both are plain Markdown that the agent reads at the start of a session as standing instructions. AGENTS.md has no required fields or headings. The differences are in where each tool looks, what it does when several files exist, and which extra features it supports.

The row that causes the most confusion is the second file. Codex uses one file per directory, so an AGENTS.override.md hides the AGENTS.md next to it rather than adding to it. Claude Code's CLAUDE.local.md is additive. Codex also builds its instruction chain once per run, so restart Codex after you edit AGENTS.md.

When Claude Code reads AGENTS.md, and when it skips it

Older guides say Claude Code ignores AGENTS.md. That changed in v2.1.277. Under the default setting, Claude Code checks for three files in your working directory and every directory above it: CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md. If it finds any of them, it reads those and not AGENTS.md. If it finds none, it reads every AGENTS.md and .claude/AGENTS.md on that path, and shows a line such as no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md in the session.

Three things do not count toward that check and load alongside AGENTS.md: your own ~/.claude/CLAUDE.md, your organisation's managed CLAUDE.md, and anything in .claude/rules/. Claude Code never reads AGENTS.override.md, AGENTS.local.md or anything under a .agents/ directory, so instructions there reach Codex only.

To change the rule, run /config in a Claude Code session and set Project instructions:

To set it once for every project, put it in ~/.claude/settings.json. Claude Code ignores this entry in a project's .claude/settings.json, so it cannot be set for a whole team from the repository. The key below needs v2.1.285 or later; earlier versions read the same entry under agents-md@builtin:

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

How Codex finds AGENTS.md

Codex starts with the file in its home directory: AGENTS.override.md if it exists and is not empty, otherwise AGENTS.md. Then it finds the project root, which by default is the nearest directory at or above you that contains .git (configurable with project_root_markers), and walks down to the directory where you started it. In each directory it takes the first of AGENTS.override.md, AGENTS.md and any names in project_doc_fallback_filenames, skipping empty files. If there is no project root, it checks only the current directory.

To make Codex read a CLAUDE.md in directories that have no AGENTS.md, add it as a fallback in ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md"]
project_doc_max_bytes = 65536

The second line raises the instruction size limit from its 32 KiB default. Treat the fallback as a stopgap. Any @path line in a CLAUDE.md means something to Claude Code, and Codex's AGENTS.md documentation describes no import syntax of its own.

Three ways to keep one source of truth

Two files that say slightly different things are the usual end state when nobody decides. Pick one of these:

1. AGENTS.md only. Both tools read it with no setup, as long as everyone runs Claude Code v2.1.281 or later and nobody adds a CLAUDE.md or CLAUDE.local.md. Versions from v2.1.277 read it too, except in some sessions such as those on Amazon Bedrock or with telemetry disabled. This is the simplest option.
2. A CLAUDE.md that imports AGENTS.md. Use this when you need instructions only Claude should see, or when some people run older Claude Code versions. Claude reads the imported file first, then the rest:

   @AGENTS.md
   
   ## Claude Code
   Use plan mode for changes under `src/billing/`.

3. A symlink, ln -s AGENTS.md CLAUDE.md, when there is nothing Claude-specific. Claude's Edit and Write tools refuse to write through a symlink and edit AGENTS.md instead, and if anyone clones the repository on Windows, Git may check the link out as a one-line text file. Use the import in that case.

Avoid /import for this. It appends a one-time copy of AGENTS.md to CLAUDE.md, which gives you two files to keep in step from that moment on.

What belongs in which file

Put everything both agents need in AGENTS.md: build and test commands, where code lives, naming conventions, and rules such as which directories not to touch. Put Claude-only material below the import in CLAUDE.md, and use .claude/rules/ with a paths list in the frontmatter for instructions that only matter for some files, since Claude loads those only when it works on matching files. Codex-only material can go in an AGENTS.override.md, but remember that it replaces the AGENTS.md in its directory for Codex, so it must repeat anything shared.

Neither file enforces anything. Claude Code's documentation says it treats CLAUDE.md as context, not enforced configuration, and points to a PreToolUse hook or a permissions.deny rule for anything that must never happen.

Ignored instruction files don't follow you into new worktrees

When you give each agent its own git worktree, a committed AGENTS.md or CLAUDE.md is there in every checkout. Ignored files are not. A CLAUDE.local.md exists only in the worktree where you created it; to share personal instructions across worktrees, import a file from your home directory, such as @~/.claude/my-project-instructions.md. The ChatGPT desktop app copies an ignored AGENTS.override.md into the local worktrees it manages, but not into worktrees you create with git worktree add.

Check what each agent actually loaded

In Claude Code, run /memory and look for the file's path, or run /context and check the list under Memory files. In Codex, run this from the directory you work in:

codex --ask-for-approval never "Summarize the current instructions."

For a record of the session, start Codex with codex -c log_dir=./.codex-log and read ./.codex-log/codex-tui.log.

Running Claude Code and Codex side by side on one project

A shared AGENTS.md matters most when both agents work on the same repository at the same time, which Armadai supports. Armadai is a native macOS app where each project folder becomes a workspace on one canvas, with Claude Code and Codex CLI tiles alongside terminals, code and notes. Its task handoff gives each run its own Git worktree, so commit any instructions a run needs, and Coordinate lets the two agents exchange plans, implementation and reviews while you set the limits. The agents use your own Claude Code and Codex accounts. Armadai costs $20 a month after a 7-day free trial that needs no card.

For the rest of the setup, including review hand-offs between the two tools, see how to use Claude Code and Codex together.