AGENTS.md vs CLAUDE.md in 2026: 7 ways to share one set of instructions across agents

Disclosure: Enjoy is our product, and its project instructions go to every agent it runs. We checked every way below against its maker’s own pages on November 9, 2026, and we say where another way is the better pick, including the free ones that need nothing but a file.

AGENTS.md vs CLAUDE.md, and what each agent reads

They’re the same thing under two names: a Markdown file of standing instructions that a coding agent reads before it works. CLAUDE.md is Claude Code’s own. AGENTS.md is the open one. Its site calls it “A simple, open format for guiding coding agents,” and says “AGENTS.md is now stewarded by the Agentic AI Foundation under the Linux Foundation.”

The split has mostly closed. Before version 2.1.277, Claude Code didn’t read AGENTS.md on its own, so a project with two agents kept two files. That version, released September 18, 2026, changed it: “Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead.” Pages that say Claude Code ignores AGENTS.md describe the versions before it. So the short answer is to write one AGENTS.md, and keep a CLAUDE.md only for rules meant for Claude alone.

Here is what each agent reads, by its own docs:

Agent	Reads AGENTS.md, checked November 9, 2026	Reads CLAUDE.md	A limit in its docs
Claude Code	Yes, from version 2.1.277, when there’s no CLAUDE.md	Yes, first	“target under 200 lines per CLAUDE.md file”
Codex	Yes, after AGENTS.override.md	Only if you add it to project_doc_fallback_filenames	32 KiB combined, by default
Grok Build	Yes	Yes: it “reads any of” six names, this one included	“loaded in full, with no size cap”
Antigravity	Yes, or GEMINI.md	Not on its rules page	24,000 bytes a file
Muse Code	Yes, first	Yes, when there’s no AGENTS.md	Project rules load only after you trust the workspace
OpenCode	Yes, first	Yes, “used if no AGENTS.md exists”	File references in AGENTS.md aren’t followed automatically
Cursor	Yes, beside its own .cursor/rules	Not on its rules page	“Keep rules under 500 lines”
GitHub Copilot	Yes, anywhere in the repository	Yes, one, in the repository root	The nearest AGENTS.md takes precedence

The rows come from Claude Code’s, Codex’s, Grok Build’s, Antigravity’s, Muse Code’s, OpenCode’s, Cursor’s and GitHub Copilot’s pages. And these are the seven ways to keep one set of instructions for all of them:

Way	Best for	Price, checked November 9, 2026	Reaches
1. One AGENTS.md, no CLAUDE.md	New projects, and teams on mixed agents	Free	All eight agents above
2. A CLAUDE.md that imports @AGENTS.md	Projects that need Claude-only rules	Free	All eight
3. A symlink from CLAUDE.md to AGENTS.md	One person on Mac or Linux, on an older Claude Code	Free	All eight
4. Codex’s fallback list, pointed at CLAUDE.md	Claude-first projects that keep CLAUDE.md	Free	Claude Code, Codex, and the four that read CLAUDE.md unaided
5. A one-time import	Moving from one agent to another	Free	Claude Code to Codex, or back
6. Ruler or Rulesync	Many tools, some with formats of their own	Free and open source	Thirty or more tools each
7. Enjoy’s project instructions	Several labs’ agents in one app	A monthly subscription, free for 7 days (pricing)	The six agents Enjoy runs

Free means nothing beyond the agents’ own plans, which their makers bill for separately.

Why two files were a problem

Reading AGENTS.md didn’t end the confusion. Three things still catch people out:

• Claude Code prefers its own file. With both files in a project, Anthropic’s docs say Claude reads “Your CLAUDE.md files only.” An old CLAUDE.md quietly hides a newer AGENTS.md.
• Codex doesn’t read CLAUDE.md unless it’s listed. Its docs say “Filenames not on this list are ignored for instruction discovery.”
• Two copies drift. When they disagree inside one agent, the same Anthropic page warns, “if two instructions contradict each other, Claude may pick one arbitrarily.”

1. One AGENTS.md, and no CLAUDE.md

Best for: new projects, open-source repositories, and teams whose members use different agents.

Put one AGENTS.md at the project root, and don’t keep a CLAUDE.md beside it. Anthropic says “Claude Code can read AGENTS.md as your project instructions, so a repository already set up for other coding agents works without adding a CLAUDE.md, an import, or a setting.” “Codex reads AGENTS.md files before doing any work,” “Cursor supports AGENTS.md in the project root and subdirectories,” and the other five read it as the table shows.

To check that it loaded:

• Claude Code: a new session shows a line such as no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md, and /memory lists the file.
• Codex: OpenAI suggests running codex --ask-for-approval never "Summarize the current instructions."
• Grok Build: grok inspect “lists each rules file Grok found, with its path and approximate token count.”

Price: free.

Watch for:

• Older versions. “Reading AGENTS.md directly requires Claude Code v2.1.277 or later.” Version 2.1.281, of September 23, extended it to “Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled.”
• A personal file turns it off. “Because CLAUDE.local.md counts, adding one to keep your own uncommitted instructions in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you.” The fix is /config, then Project instructions set to claude-md-and-agents-md, which reads both.
• The variants don’t carry over. Claude Code doesn’t read “AGENTS.local.md, AGENTS.override.md, or anything under a .agents/ directory.” Codex reads AGENTS.override.md before AGENTS.md, and Antigravity and Muse Code both check .agents/AGENTS.md.
• Nested files. The format’s site says “Agents automatically read the nearest file in the directory tree,” but Antigravity “doesn’t load rules from subfolders below the workspace folder, even when the agent reads or edits files there.”

2. A CLAUDE.md that imports AGENTS.md

Best for: projects that already have a CLAUDE.md, or that need rules only Claude should follow.

Keep the shared rules in AGENTS.md, and make CLAUDE.md a short file that starts by importing it. This is Anthropic’s own example:

@AGENTS.md

## Claude Code

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

“Add any Claude-specific instructions below the import, and Claude reads the imported file first, then the rest.” If you set this up before September, you can leave it: “Keeping the import never makes Claude read AGENTS.md twice.” It’s also Anthropic’s answer for the sessions that can’t load AGENTS.md directly.

Price: free.

Watch for: the @ import is Claude Code’s syntax, not the format’s. OpenCode’s rules page says it “doesn’t automatically parse file references in AGENTS.md,” so keep AGENTS.md whole, not a list of links to other files. OpenCode’s own way to add files is the instructions list in opencode.json. Imports don’t save context either: they “help you organize a long file but don’t reduce its context cost.” And CLAUDE.md isn’t private to Claude. Grok Build “reads any of” six file names in a folder, CLAUDE.md among them, so write the Claude-only part so that another agent reading it does no harm.

3. A symlink from CLAUDE.md to AGENTS.md

Best for: one person on a Mac or Linux whose Claude Code is older than 2.1.277.

ln -s AGENTS.md CLAUDE.md

“If you don’t need Claude-specific content, a symlink also works,” Anthropic says. The format’s own site uses the trick for old file names: “Rename existing files to AGENTS.md and create symbolic links for backward compatibility.”

Price: free.

Watch for: Windows. Anthropic’s advice is that “if you or anyone who clones the repository works on Windows, use the @AGENTS.md import instead,” because “Git checks a committed symlink out as a plain text file unless core.symlinks is enabled, which leaves that clone with a one-line CLAUDE.md in place of your instructions.” Claude can’t edit through the link either: “the Edit and Write tools refuse to write through a symlink.” On a current Claude Code you no longer need it. For “A CLAUDE.md symlinked to AGENTS.md,” the docs’ advice is “nothing, or delete the symlink.”

4. Point Codex at CLAUDE.md

Best for: projects built around Claude Code that want CLAUDE.md to stay the one file, with Codex as the visitor.

Codex can be told to accept other names. In each folder it “checks for AGENTS.override.md, then AGENTS.md, then any fallback names in project_doc_fallback_filenames.” OpenAI’s example lists a TEAM_GUIDE.md. The same setting with CLAUDE.md, in ~/.codex/config.toml, would be:

project_doc_fallback_filenames = ["CLAUDE.md"]

That line follows OpenAI’s pattern, but it’s ours, and we didn’t run it. Four other agents need no setting. OpenCode uses a CLAUDE.md “if no AGENTS.md exists,” Muse Code checks for one right after AGENTS.md, Grok Build reads it, and GitHub’s docs say “you can use a single CLAUDE.md or GEMINI.md file stored in the root of the repository.”

Price: free.

Watch for: the list lives in each person’s ~/.codex/config.toml, not in the repository, so every teammate sets it on every machine. OpenAI’s configuration page calls fallbacks “additional filenames to try when AGENTS.md is missing at a directory level,” and “Codex includes at most one file per directory.” Codex’s page describes no import syntax, so don’t count on it following the @ imports in a CLAUDE.md. And Cursor’s and Antigravity’s rules pages don’t mention CLAUDE.md, so this way leaves them out.

5. Import once, when you’re moving

Best for: leaving one agent for another, not running both.

Both labs will convert the other’s file. OpenAI’s import guide says “The desktop app can import from Claude Code, Claude Cowork, or Cursor. Codex CLI can import from Claude Code or Cursor.” Open Settings > Import in the ChatGPT desktop app, or type /import in the CLI, and instruction files become AGENTS.md. “Importing doesn’t change or delete your existing agent setup.”

Going the other way, Claude Code’s /import “appends a one-time copy of instruction files such as AGENTS.md to the matching CLAUDE.md and carries over MCP servers, commands, subagents, and skills.” Its /init “reads other tools’ instruction files and incorporates the relevant parts into the generated CLAUDE.md,” Cursor’s rules and Copilot’s instructions among them.

Price: free.

Watch for: a copy is a second file. Claude Code’s is “a one-time copy,” so it’s out of date from your next edit. The ChatGPT desktop app can “turn on automatic updates to keep imported work in sync with the original agent,” but OpenAI’s page describes that for the app, not the CLI. If you’ll keep using both agents, pick one of the first four ways instead.

6. A sync tool: Ruler or Rulesync

Best for: teams on many tools, some of which want a format of their own, or who also want MCP servers and skills kept in step.

Both tools keep one source and write every agent’s file from it.

• Ruler offers “a single source of truth for all your AI agent instructions, automatically distributing them to the right configuration files.” Your rules live “in a dedicated .ruler/ directory using Markdown files,” and npx @intellectronica/ruler apply writes them out. Its .gitignore feature “Keeps generated agent config files out of version control automatically.”
• Rulesync calls itself “A Node.js CLI tool that automatically generates configuration files for various AI development tools from unified AI rule files.” rulesync import --targets claudecode reads an existing CLAUDE.md, and rulesync generate --targets "*" --features "*" writes the rest. Its table covers rules, MCP, commands, subagents, skills, hooks and permissions.

Price: free. Both are open source under the MIT license.

Watch for: a build step. You edit the source and run the tool, and the agents read generated files. Forget the run, and they read old rules. Ruler’s README carries a “Beta Research Preview” notice: “Please test this version carefully in your environment.” Its table has no row for Grok Build or Muse Code. Rulesync’s lists “Grok CLI” and “Meta Muse Code.” Since most agents now read AGENTS.md directly, for instructions alone these tools matter most with the agents that don’t: Ruler’s table shows it writing .clinerules for Cline, WARP.md for Warp, and a steering file for Kiro.

7. Enjoy’s project instructions

Best for: people who run several labs’ agents in one app, including in projects that aren’t Git repositories.

Enjoy is a desktop app for Mac, Windows and Linux that runs Claude Code, Codex, Grok Build, Antigravity, Muse Code, and local models through OpenCode, on the plans you already have. Each project has an Instructions box in its settings, and Enjoy’s help says “Instructions apply to every conversation in the project, whichever agent you use. Agents receive them when they start working in a conversation, and again after you change them.”

• No file to name. The same text goes to whichever agent has the conversation, including after you switch agents partway through.
• An agent can edit them. Ask one to “Add to the project instructions: commit when you finish a task,” and “every agent in the project follows them from its next message.”
• Your files keep working. “Claude Code, Codex, and Muse Code also read instruction files kept in the project folder,” and “Those keep working in Enjoy.”
• They follow you to your other computer. When two of your computers sync a project, what syncs is “conversations, docs, workflows, and the project’s agent instructions.”

Price: one monthly subscription on top of your AI plans, and the first seven days are free, with a card to start. It includes your phone and any browser and one computer; each other computer costs extra each month, and each teammate you invite needs a subscription of their own. See pricing.

Watch for: “Enjoy keeps the instructions with the project’s conversations and documents, not in the project folder.” They don’t travel with the repository, so a colleague who clones it, a CI job, or the same agent started in a terminal never sees them. Enjoy’s help says to use the files “if you also run the agent outside Enjoy, or want the instructions saved with the project’s files,” and its advice on having both is “Keep the same rule in only one place, so they can’t disagree.” The iPhone app doesn’t show the instructions. Enjoy isn’t open source, it’s a monthly subscription on top of your AI plans once the free week ends, and scheduled workflows run only while your computer is awake with Enjoy open.

Your own rules, for every project

Everything above is about a project’s file. Your personal rules, the ones you want in every project, have a home in each agent, and little is shared:

• Claude Code: ~/.claude/CLAUDE.md
• Codex: ~/.codex/AGENTS.md
• OpenCode: ~/.config/opencode/AGENTS.md
• Antigravity: ~/.gemini/AGENTS.md
• Grok Build: “Global rules in ~/.grok/”
• Cursor: User Rules, “defined in Customize → Rules”

Only OpenCode borrows another agent’s: it reads ~/.claude/CLAUDE.md “if no ~/.config/opencode/AGENTS.md exists.” For the rest, it’s a file each, kept in step by hand.

When to keep a separate CLAUDE.md

If everyone on the project uses only Claude Code, nothing needs to change. CLAUDE.md is still what Claude reads first, and renaming it gains you nothing until a second agent arrives.

Keep one beside AGENTS.md, with the import from way 2, when:

• You have Claude-only rules, such as when to use plan mode.
• You rely on what only CLAUDE.md gets. For an AGENTS.md read on its own, Anthropic’s table says InstructionsLoaded hooks “Don’t fire,” and in folders added with --add-dir, where a CLAUDE.md can be set to load, “Their AGENTS.md doesn’t load.”
• Some sessions can’t read AGENTS.md. That’s when “You’re on a Claude Code version before v2.1.277,” or “You used /plugin to disable the built-in plugin that reads AGENTS.md.”

Whichever file you keep, keep it short. Claude Code’s docs say longer files “consume more context and reduce adherence,” Codex stops adding files at 32 KiB by default, and Antigravity “truncates any single rule file that exceeds 24,000 bytes.”

How we compared

We read the AGENTS.md site, Anthropic’s Claude Code memory docs and changelog, OpenAI’s Codex docs on AGENTS.md, advanced configuration and importing, OpenCode’s rules, xAI’s Grok Build project rules, Meta’s Muse Code configuration, Google’s Antigravity rules, Cursor’s rules, GitHub’s Copilot instructions page, Ruler’s and Rulesync’s READMEs and licenses, and Enjoy’s own help on November 9, 2026, and every one is linked below. The examples are the makers’ own, except the Codex fallback line, which we adapted and marked. We didn’t run these setups ourselves. We quote each maker’s own words for its limits, and where a rules page doesn’t mention a file, we say that, not that the agent ignores it. These agents ship weekly, so we recheck this guide against its sources at least once a month, and the date at the foot of the page says when we last did.