AGENTS.md vs CLAUDE.md: Does Claude Code or Codex Read Both?

If you have both Claude Code and Codex in your team's toolbox, you have probably typed the same question into a search bar: does Claude Code read AGENTS.md? Does it fall back to it if CLAUDE.md is missing? Do you need to maintain both files, or is there a way to keep them in sync?

The official answer, straight from the Claude Code memory documentation, is short:

Claude Code reads CLAUDE.md, not AGENTS.md.

There is no automatic fallback. If your repo only has AGENTS.md, Claude Code will not load it on its own. But the documentation also describes three first-class patterns for making one source of truth work for both agents. None of them require you to duplicate instructions.

Why this question keeps coming up

AGENTS.md started as a Codex convention and has spread across the ecosystem. Most non-Anthropic coding agents now look for it by default. CLAUDE.md is the equivalent file Claude Code has always used, and it predates AGENTS.md by enough that Anthropic chose to keep the name rather than rename around a younger convention.

The result is a real interoperability problem for any team that runs more than one agent:

A CLAUDE.md-only repo confuses Codex, Cursor, and anything else that expects AGENTS.md.
An AGENTS.md-only repo gets ignored by Claude Code.
Maintaining both by hand means every project rule has to be written, edited, and reviewed twice.

The good news is you do not have to pick.

Option 1: import AGENTS.md from CLAUDE.md (recommended)

Claude Code supports @path/to/file imports inside CLAUDE.md. Imported files are expanded into the session context at launch, exactly as if their contents were inline. So the minimum-viable shared setup is a CLAUDE.md that pulls in AGENTS.md:

@AGENTS.md

## Claude Code

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

AGENTS.md stays the source of truth for every tool in your stack. CLAUDE.md exists only to wire the import and hold the small handful of Claude-specific overrides you actually need. Codex reads AGENTS.md directly. Claude Code reads CLAUDE.md, expands the @AGENTS.md line, and ends up with the same instructions plus your overrides.

This is the pattern Anthropic itself recommends in the docs. It is the cleanest answer for almost every team.

Option 2: symlink CLAUDE.md to AGENTS.md

If you have nothing Claude-specific to say and want exactly one file on disk, a symlink works:

ln -s AGENTS.md CLAUDE.md

Claude Code follows the symlink and reads AGENTS.md byte-for-byte. There is no second file to keep updated and no merge logic to debug.

The caveat: on Windows, creating a symlink requires Administrator privileges or Developer Mode. Cross-platform teams should default to the @AGENTS.md import instead. The import works identically on every OS and survives git clone without anyone needing elevated permissions.

Option 3: let /init merge them for you

If you are bootstrapping Claude Code in a repo that already has an AGENTS.md (or a .cursorrules or .windsurfrules), running /init reads those files and incorporates the relevant parts into the generated CLAUDE.md automatically. This is the right starting point if your AGENTS.md has grown beyond a clean shared spec and you want Claude Code to extract the parts that apply to it specifically.

After /init, you still own the resulting CLAUDE.md. If you want it to stay in sync with AGENTS.md going forward, convert it to the import pattern from Option 1 and delete the duplicated content.

Adding Codex to a Claude Code project (4-step migration)

If you already have a working CLAUDE.md and need to add Codex (or any other AGENTS.md-reading tool) to your stack, here is the shortest path to one shared instruction file. The reverse direction — adding Claude Code to a Codex project — is the same four steps with the file names swapped.

Step 1 — Decide which file is canonical

Pick AGENTS.md as your canonical source of truth. It is the file most non-Claude tools read by default, and an @AGENTS.md import inside CLAUDE.md travels with the repo for every Claude Code user. Making CLAUDE.md canonical instead works mechanically, but it pushes per-machine setup onto everyone who runs Codex, Cursor, OpenCode, or anything else in the broader ecosystem.

Step 2 — Wire CLAUDE.md to import AGENTS.md

Move the contents of your existing CLAUDE.md into AGENTS.md, then replace CLAUDE.md with a one-line import plus whatever Claude-specific overrides you actually need:

@AGENTS.md

Claude Code expands the import at session start, so the model sees exactly the same instructions it always has. See Option 1 above for the full pattern and a worked example with overrides.

Step 3 — (Optional) Configure Codex to also read CLAUDE.md

If parts of your monorepo still ship CLAUDE.md without an AGENTS.md alongside it — or you want Codex to pick up the small overrides that live in CLAUDE.md below the import line — add the fallback to ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md"]

The full mechanics (lookup order, per-directory rules, the user-level caveat) are in the section on the other direction below. Skip this step entirely if your CLAUDE.md is just the one-line import wrapper.

Step 4 — Verify Codex actually loaded AGENTS.md on the next run

Start a fresh Codex session at the repo root and ask the model to quote back a distinctive line from AGENTS.md. If it can, the file is loaded. If it cannot, the usual culprits are launching Codex from outside the git root (so the per-directory walk never reaches the file) or an AGENTS.override.md somewhere in the directory chain shadowing what AGENTS.md says.

What about the other direction: can Codex read CLAUDE.md?

The symmetric question: if your repo only has CLAUDE.md, will Codex pick it up?

By default, no. Codex CLI reads AGENTS.md and AGENTS.override.md. CLAUDE.md is not part of the default discovery list. But unlike Claude Code, Codex exposes a configuration setting for adding fallback filenames. In ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md", "COPILOT.md"]

With that set, Codex's per-directory lookup becomes AGENTS.override.md → AGENTS.md → fallback names, in order, walked from the Git root down to the current working directory. At most one file is picked up per directory, so CLAUDE.md is read only where no AGENTS.md exists alongside it. The full lookup rules are in the Codex AGENTS.md guide.

The two ecosystems end up symmetric in shape but asymmetric in mechanism:

	Default behavior	How to read the other file
Claude Code	Reads `CLAUDE.md` only	`@AGENTS.md` import inside `CLAUDE.md`, or `ln -s AGENTS.md CLAUDE.md`
Codex CLI	Reads `AGENTS.md` / `AGENTS.override.md` only	`project_doc_fallback_filenames = ["CLAUDE.md"]` in `~/.codex/config.toml`

One practical caveat about the Codex fallback: it lives in ~/.codex/config.toml, which is a user-level file. It does not travel with the repo. New teammates who clone the project will not pick up CLAUDE.md until they set the same fallback list themselves. The Claude Code import pattern, by contrast, lives inside the repo and works for everyone on first clone with no per-machine setup.

That asymmetry is the main reason we still recommend AGENTS.md as the canonical source of truth and CLAUDE.md as a thin import wrapper, even though both directions are technically achievable. One file travels with the repo; the other depends on every developer remembering to configure their CLI.

What about CLAUDE.local.md, rules, and managed policy?

The compatibility question usually surfaces because someone is trying to make a project-level file work across tools. But Claude Code has a full hierarchy of instruction files that also matters when you are running more than one agent:

CLAUDE.md and ./.claude/CLAUDE.md — team-shared, committed to the repo.
CLAUDE.local.md — personal, gitignored.
.claude/rules/ — modular, with paths: frontmatter for path-scoped rules.
Managed policy CLAUDE.md — organization-wide, deployed by IT, cannot be excluded.

AGENTS.md is a single flat file. There is no AGENTS.local.md, no rules directory, no managed-policy layer. Other agents that read AGENTS.md mostly do not have those concepts either. So the @AGENTS.md import covers the team-shared layer cleanly, but the rest of the Claude Code hierarchy stays Claude-specific by design.

In practice this means:

Put cross-tool rules in AGENTS.md, imported from CLAUDE.md.
Put Claude-specific behavior in CLAUDE.md below the import.
Put personal preferences in CLAUDE.local.md, gitignored.
Use .claude/rules/ with paths: frontmatter for instructions that only apply to part of the codebase.

That gives you one shared file across tools without giving up the features that make Claude Code's instruction layer useful.

Other tools: Cursor, OpenCode, Aider, Continue, Cline

AGENTS.md has spread beyond Codex, but adoption is uneven. Some tools read it natively, some read it through a configuration knob, and a few still want their own convention file. Here is what each major non-Claude coding agent does at time of writing.

Tool	Reads AGENTS.md natively?	Native config file(s)	Notes
Cursor	Yes — natively; the Cursor docs present `AGENTS.md` as an alternative to `.cursor/rules`	`.cursor/rules/*.mdc` (current directory format) or legacy `.cursorrules`	Nested `AGENTS.md` files in subdirectories apply when working in those directories. No `AGENTS.local.md` equivalent; use `.cursorignore` for per-machine excludes.
OpenCode	Yes — primary file; falls back to `CLAUDE.md` if no `AGENTS.md` exists	`AGENTS.md` (project), `~/.config/opencode/AGENTS.md` (global)	Also falls back to `~/.claude/CLAUDE.md` at the global level. Disable Claude compatibility with `OPENCODE_DISABLE_CLAUDE_CODE=1`.
Aider	No by default; loads only when explicitly configured	`.aider.conf.yml` + `CONVENTIONS.md`	Add `read: AGENTS.md` to `.aider.conf.yml` (or `read: [CONVENTIONS.md, AGENTS.md]` for multiple) to autoload it, or pass `--read AGENTS.md` per session.
Continue	Yes — added in early 2026 via continuedev#7717, loaded as an always-apply rule	`.continue/rules/*.md` or `config.yaml` for tool-specific rules	Continue loads `AGENTS.md` from the repo root alongside its native `.continue/rules/` system, so the same instructions reach both.
Cline	No native autoload	`.clinerules` (single file) or `.clinerules/*.md` (directory)	The Cline community pattern is a "Memory Bank" — a `.clinerules/` directory with several scoped markdown files, not a single `AGENTS.md`.

A few practical consequences:

Cursor, OpenCode, and Continue unify cleanly. Point them at AGENTS.md, keep the @AGENTS.md import from CLAUDE.md, and four agents (Claude Code, Cursor, OpenCode, Continue) read the same source of truth on git clone with no further setup.
Aider joins the same arrangement with one extra line in .aider.conf.yml. Commit that config file to the repo so the configuration travels with everyone who clones it.
Cline still needs its own files. The pragmatic option is to keep the source of truth in AGENTS.md and either symlink (ln -s AGENTS.md .clinerules on Unix, with the Windows caveat from Option 2) or use a small build step to mirror content. There is no native fallback to lean on.

The shape of the ecosystem is clear: AGENTS.md is winning as the shared convention, but "winning" still means "most agents read it, with caveats." Until adoption is universal, the import-or-fallback pattern from earlier in this post is the only reliable way to keep one file and serve every agent on the team. Verify each tool's behavior against its current docs before committing — these defaults shift release to release.

What to actually put in AGENTS.md (and what to keep out)

The file mechanics are settled. The harder question is what belongs in the file in the first place. Most AGENTS.md files we see in the wild are either too thin to help the model on its first run or so dense the model burns context tokens on instructions it never needed.

What belongs in AGENTS.md

Architecture overview. One short paragraph: what this repo is, what it produces, which language and framework, where the entry points live. The model can infer the rest from code; what it cannot infer is intent.
Build, test, and run commands. Be specific. pnpm test:fast if pnpm test runs the slow suite. make dev if that is the only command that wires up your local mocks. Agents waste enormous amounts of time guessing this and then re-guessing it after every failure.
Conventions and constraints. "Don't bump major dependencies without filing an issue first." "All public exports go through src/index.ts." "Database migrations are forward-only — never edit a shipped migration." These are the rules an experienced teammate would tell a new hire on day one.
Repo-specific gotchas. The thing that bit the last engineer. Why the legacy/ directory is structured oddly. Which test suite requires the dev container running. These are the highest-leverage entries in the file because they cannot be derived from reading the code.
Tool-specific overrides under a labeled subsection. A ## Claude Code or ## Codex heading at the bottom of AGENTS.md works fine. Most tools read the whole file regardless; the heading is for the humans maintaining it.

What to keep out

Secrets and credentials. Never. AGENTS.md is committed and the agent's context window is logged. If you need to give an agent credentials, do it through the runtime — see How to scope credentials for an AI coding agent.
Things the model can derive from reading code. Don't re-document the API surface, the function signatures, or the directory layout. The agent reads the code. Restating it in AGENTS.md wastes context and rots the moment the code changes.
Vibes. "Be careful with the auth module." Not actionable. Either give the rule ("never call getUser() without a tenant ID — it returns cross-tenant data") or leave it out.
Vendor-specific lock-in. Write the file in the model-agnostic style even if you only use one tool today. Tomorrow's stack is rarely the same as today's, and rewriting AGENTS.md against a deadline is the worst time to debug instruction drift.

Override patterns

If you keep AGENTS.md canonical and use @AGENTS.md from CLAUDE.md, the natural place for Claude-only behavior is below the import:

@AGENTS.md

## Claude Code

Use plan mode for any change that touches `src/billing/`.
Never run `pnpm db:reset` — use the seeded fixture instead.

Codex never sees that section. Claude Code reads it after the imported content, so the override applies on top of the shared rules.

FAQ

Does Claude Code automatically read AGENTS.md?

No — Claude Code reads CLAUDE.md only, with no automatic fallback to AGENTS.md. If your repo ships only AGENTS.md, Claude Code will not load it. Use @AGENTS.md inside a one-line CLAUDE.md, or symlink CLAUDE.md to AGENTS.md, to wire them together.

Does Codex CLI automatically read CLAUDE.md?

Not by default, but Codex exposes a configuration knob that adds it as a fallback. Set project_doc_fallback_filenames = ["CLAUDE.md"] in ~/.codex/config.toml and Codex will read CLAUDE.md in any directory where no AGENTS.md exists alongside it. The setting lives in a per-user file, so each teammate has to configure it themselves.

What is the CLAUDE.md equivalent for Codex CLI?

AGENTS.md is the direct equivalent. Same purpose (project-level instructions to the agent), same scope (committed to the repo, applies to everyone who runs the tool), same plain-markdown format. The two ecosystems converged on the same pattern with different filenames.

Can Codex use CLAUDE.md?

Yes, if you tell it to. Codex doesn't read CLAUDE.md out of the box, but the project_doc_fallback_filenames setting in ~/.codex/config.toml adds it to the per-directory lookup. Without that setting Codex ignores CLAUDE.md entirely.

Does Codex have a CLAUDE.md equivalent?

Yes — it's AGENTS.md. Codex looks for AGENTS.override.md first, then AGENTS.md, walking from your git root down to the current working directory and picking at most one file per directory. The convention has since spread to most non-Anthropic coding agents.

Should I use AGENTS.md or CLAUDE.md if I use both Claude Code and Codex?

Use AGENTS.md as canonical and a one-line CLAUDE.md that imports it via @AGENTS.md. That way the file travels with the repo and every teammate gets the right behavior on git clone — no per-machine setup, no duplicated content. The reverse arrangement (canonical CLAUDE.md with a Codex fallback) works but requires every developer to configure their Codex CLI manually.

Why doesn't Codex read CLAUDE.md by default?

Because AGENTS.md is the open convention Codex was built around, and CLAUDE.md is Anthropic-specific. Neither tool reads the other's file natively for the same reason — they were each built around a specific filename and the cross-tool compatibility patterns came later.

Can I convert CLAUDE.md to AGENTS.md automatically?

Yes — and the simplest "conversion" is to rename the file. The two formats are identical (plain markdown, no required structure, no frontmatter). For Claude Code compatibility after the rename, drop in a one-line CLAUDE.md containing @AGENTS.md, or symlink CLAUDE.md to AGENTS.md.

Does Cursor support AGENTS.md?

Yes — Cursor reads AGENTS.md natively. The Cursor docs present it as an alternative to .cursor/rules, and nested AGENTS.md files in subdirectories apply when working in those directories. The shared-source-of-truth pattern works without a bridge file.

Does OpenCode read AGENTS.md or CLAUDE.md?

Both — AGENTS.md is primary and CLAUDE.md is a built-in fallback. OpenCode reads AGENTS.md first, and if none is present in a directory it picks up CLAUDE.md in the same place. Set OPENCODE_DISABLE_CLAUDE_CODE=1 to turn the fallback off entirely.

What is `.agents.local.md` used for?

There is no widely-supported AGENTS.local.md analog to CLAUDE.local.md. AGENTS.md is a single flat file by design, and none of the major tools that read it support a .local variant. For personal, gitignored overrides, use Claude Code's CLAUDE.local.md or the equivalent local-config mechanism in your other tools.

How do I verify my AGENTS.md was loaded by Codex?

Start a fresh Codex session at the repo root and ask the model to quote back a distinctive line from your AGENTS.md. If it can, the file is loaded; if it cannot, you almost certainly have a working-directory or git-root issue with Codex's per-directory lookup, or an AGENTS.override.md higher in the tree is shadowing it.

What happens if both AGENTS.md and CLAUDE.md are in the same project?

Each tool reads its own file and ignores the other. Claude Code reads CLAUDE.md and never looks at AGENTS.md. Codex reads AGENTS.md and never looks at CLAUDE.md unless you set the fallback list. If the two files disagree, the two agents will behave differently — which is why the canonical-plus-import pattern is the recommended setup.

Yes — keep AGENTS.md as the canonical file and add a thin wrapper only for tools that don't read it natively. Cursor, Codex, OpenCode, and Continue read AGENTS.md directly. Claude Code needs a one-line CLAUDE.md containing @AGENTS.md. Aider needs read: AGENTS.md in .aider.conf.yml.

Does AGENTS.md support imports the way CLAUDE.md does with `@path/to/file`?

No — AGENTS.md is a single flat markdown file with no import mechanism in the spec. Tools that read it concatenate the file's contents into the model context as-is. The closest pattern to modularity is the monorepo convention: drop an AGENTS.md into each subpackage, and most tools that read it will pick up the nearest one in the directory tree.

The bigger problem the file does not solve

CLAUDE.md and AGENTS.md are about instructions to the model. They are not the rest of the harness.

In a production setup, swapping Claude Code for Codex (or running both side by side) is not just a question of whether they read the same markdown file. It is a question of:

Which execution sandboxes the agent is wired up to connect to.
Which MCP servers the agent has access to.
How secrets are injected so the model never sees them in context.
Which internal services the agent can reach over the network.
How idle timeouts, scaling, and audit logs are configured.
Which model and API keys back the agent.

Two coding agents that happen to read the same AGENTS.md can still have wildly different deployment posture, security boundaries, and observability. Making the instruction file portable is a one-line change. Making the rest of the runtime portable is the actual work.

How Agyn handles this

Agyn is the open-source Kubernetes runtime we build for deploying coding agents inside enterprise infrastructure. The harness around the model — containers, MCP servers, secrets, network policy, observability — lives in Terraform. The agent itself is one line of that Terraform.

To switch an agent from Claude Code to Codex, you change two lines — the init_image and the model it talks to:

resource "agyn_agent" "support" {
  organization_id = agyn_organization.acme.id

  name       = "Support"
  nickname   = "support"

  # Swap these two lines to change the agent runtime.
  # init_image determines which agent CLI runs; model must match its vendor.
  model      = agyn_llm_model.claude_opus_4_8.name
  init_image = "ghcr.io/agynio/agent-init-claude:v1.0.0"
  # model    = agyn_llm_model.gpt_5_3_codex.name
  # init_image = "ghcr.io/agynio/agent-init-codex:v1.0.0"

  instructions = file("./agents/support/instructions.md")

  image        = "ghcr.io/agynio/agent-runtime:v1.0.0"
  idle_timeout = "5m"
  availability = "internal"
}

instructions is the field that resolves to CLAUDE.md or AGENTS.md depending on init_image. You write the content once, in plain markdown, and Agyn renders it into the container at ~/.claude/CLAUDE.md when the Claude init image is active or ~/.codex/AGENTS.md when the Codex one is. The Terraform stays identical across the swap — the same string lands at the path the active agent expects.

The agent runtime container, MCP servers, secrets, OpenZiti zero-trust networking, per-agent observability, and access policy all stay in place. Everything Agyn manages — the harness — keeps working unchanged. Only the agent loop itself swaps.

The agent's instruction file is part of the agent definition, not part of every repo it operates on. You write the instructions once in Terraform, and Agyn renders them into the runtime container at the user-level path the active agent expects — ~/.claude/CLAUDE.md when the init image is Claude Code, ~/.codex/AGENTS.md when it is Codex. Because they sit at the user-instruction layer, those instructions apply across every repository the agent works in.

For repo-level instructions — project-specific build commands, conventions, architectural notes that only matter inside one codebase — the patterns from the start of this post still apply. Use AGENTS.md as the canonical file with @AGENTS.md imported from CLAUDE.md, or one of the symlink / /init variants. Agyn does not replace the repo-level layer; it adds the global agent-level layer on top of whatever the repo already has, and the two compose at runtime exactly as Claude Code and Codex normally compose user-level and project-level instructions.

The model layer is becoming a commodity. The harness — the runtime around the agent — is where compatibility actually lives. CLAUDE.md vs AGENTS.md at the repo level is the easy half of that problem. The global instruction layer, the secrets boundary, the MCP wiring, the network policy, and the observability are the other half. We built Agyn for that half.

Claude Code docs on CLAUDE.md and AGENTS.md: code.claude.com/docs/en/memory
Agyn platform: github.com/agynio/platform
Previously: Introducing Agyn

Get new agent engineering posts in your inbox