# One Repo, Many Agent CLIs: Keeping AGENTS.md and CLAUDE.md in Sync

> One AGENTS.md now works as the rules file for Claude Code, Codex, Cursor, OpenCode, Copilot, Grok, Kimi, and Antigravity. The per-CLI read paths, verified October 2026, and when you still need the import or symlink bridge.

Updated October 21, 2026 (first published August 20, 2026) · by the AQ team · Canonical: https://aq.dev/guides/keep-agents-md-and-claude-md-in-sync/

Claude Code reads AGENTS.md natively as of version 2.1.277, released on September 18, 2026: in a project with no CLAUDE.md, it loads AGENTS.md as its project instructions automatically. That changes the default advice for running several agent CLIs against one repository. The simplest setup is now a single AGENTS.md and no CLAUDE.md at all, which Codex, Cursor, OpenCode, GitHub Copilot, Claude Code, xAI's Grok CLI, Moonshot's Kimi CLI, and Google's Antigravity CLI all read natively as of October 2026: one rules file genuinely covers every major harness a team runs, for the first time. The `@AGENTS.md` import and the committed symlink, previously the only bridges, are now fallbacks: you still need one on Claude Code versions before 2.1.277, and a CLAUDE.md anywhere in or above your working directory still takes precedence whenever both files exist. This guide covers the new default, the verified read paths of all eight major CLIs, the precedence rules that decide which file Claude Code actually reads, and what to do with the per-tool trees (skills, commands, rules) that still refuse to converge.

## Why one repo ends up with three instruction files

[AGENTS.md](https://aq.dev/glossary/agents-md/) started as OpenAI's convention for Codex in August 2025 and has since become the cross-tool standard: it was donated to the Linux Foundation's Agentic AI Foundation in December 2025, and Codex, Cursor, OpenCode, GitHub Copilot, Grok CLI, Kimi CLI, and Antigravity CLI all read it natively as of October 2026.

Claude Code was the notable holdout until September 18, 2026. For over a year, Anthropic's documentation was explicit that Claude Code read CLAUDE.md and not AGENTS.md, the GitHub request to change that was the most upvoted on the tracker and marked not planned, and guides like this one taught an import or symlink bridge as the only option. Version 2.1.277 reversed that. The changelog entry reads, in full: "Added AGENTS.md support: in a project with no CLAUDE.md, Claude Code reads AGENTS.md instead; change it under 'Project instructions' in /config." Version 2.1.281 extended the support to sessions on Amazon Bedrock, Google Vertex AI, Microsoft Foundry, LLM gateways, and sessions with telemetry disabled, which had initially been excluded. The support has kept maturing since: as of October 2026 the changelog shows 2.1.290 fixing a subdirectory's AGENTS.md not being attached when a file under it is @-mentioned, and fixing instruction files symlinked outside the working directory, so when AGENTS.md behaves oddly, updating the CLI is the first thing to try.

The drift problem the old bridges solved has not disappeared, though. A repository that contains both files still feeds Claude Code only CLAUDE.md by default, so a team that fixes the test command in AGENTS.md while an old CLAUDE.md lingers gets exactly the stale-instructions failure this guide has always been about: someone updates one file, the other goes stale, and a week later one CLI "ignores the conventions." It did not ignore anything. It read the other file.

| Tool | Reads natively (as of October 2026) |
| --- | --- |
| Codex CLI | AGENTS.md per directory (AGENTS.override.md wins if present, at most one file per directory), plus a global AGENTS.override.md or AGENTS.md in ~/.codex; files concatenate from the repo root down until `project_doc_max_bytes` (32 KiB by default), and `project_doc_fallback_filenames` can add extra filenames to the search |
| Claude Code | CLAUDE.md, CLAUDE.local.md and .claude/rules/ when present; AGENTS.md and .claude/AGENTS.md when no CLAUDE.md or CLAUDE.local.md exists in the working directory or above it (v2.1.277 and later); @path imports work in both |
| Cursor | AGENTS.md in the project root and in subdirectories (nested files apply to their own directory and its children, and the more specific instructions win), plus .cursor/rules/*.mdc (the .mdc extension is required; a plain .md file there is not used as a rule) |
| OpenCode | AGENTS.md (project root, and global at ~/.config/opencode/AGENTS.md), falling back to CLAUDE.md and ~/.claude/CLAUDE.md unless OPENCODE_DISABLE_CLAUDE_CODE=1 is set, plus extra files, globs, or URLs listed under instructions in opencode.json |
| GitHub Copilot | AGENTS.md anywhere in the repository (the nearest one takes precedence), plus .github/copilot-instructions.md, or a single root CLAUDE.md or GEMINI.md as the alternative |
| Grok CLI | AGENTS.md, Agents.md, or AGENT.md in every directory from the repo root down to the working directory, plus CLAUDE.md, Claude.md, and CLAUDE.local.md, every *.md in .grok/rules/, and .claude/rules/ and .cursor/rules/ for compatibility; gitignored files are skipped and deeper files win on conflicts |
| Kimi CLI | AGENTS.md merged from the project root down to the working directory, including a .kimi/AGENTS.md |
| Antigravity CLI | GEMINI.md and AGENTS.md in the active directory, plus global rules at ~/.gemini/GEMINI.md (the agy binary is Google's successor to Gemini CLI, and agy plugin import gemini carries an existing Gemini CLI setup over) |

## Does one AGENTS.md cover every CLI your team runs?

For repo-level rules, yes: a single AGENTS.md at the repository root is read by all eight tools in the table above, verified on each vendor's own documentation as of October 2026. Three differences survive the convergence, and they are worth knowing before you declare the migration done.

**First, the precedence traps.** Claude Code reads AGENTS.md only when no CLAUDE.md or CLAUDE.local.md exists in or above the working directory (Step 2 covers the bridge for that). OpenCode has the mirror-image rule: it prefers AGENTS.md and falls back to CLAUDE.md only when no AGENTS.md exists. Grok CLI sidesteps the question by reading both families of file in every directory. So a repository that keeps both files feeds different tools different content, which is exactly the drift this guide exists to prevent: converge on AGENTS.md and bridge or delete the rest.

**Second, each tool also reads a personal, home-directory rules file that never leaves your machine.** These are where individual preferences belong ("answer tersely", "never push without asking"), and they are per-person and per-tool by design:

| Tool | Personal global file (as of October 2026) |
| --- | --- |
| Codex CLI | AGENTS.override.md or AGENTS.md in ~/.codex (only the first non-empty file is used) |
| Claude Code | ~/.claude/CLAUDE.md (loads alongside a repo AGENTS.md; it does not count against the precedence check) |
| OpenCode | ~/.config/opencode/AGENTS.md, falling back to ~/.claude/CLAUDE.md when it does not exist |
| Grok CLI | Global rules in ~/.grok/, loaded before any repo file |
| Antigravity CLI | ~/.gemini/GEMINI.md, applied across all workspaces |
| Kimi CLI | None documented: its docs describe project files only |

**Third, instruction files are only one of a coding agent's memory layers.** They carry the rules you write; they carry nothing an agent learned in a session, and vendor auto memory (the notes Claude Code writes for itself, for example) stays per-person and per-tool. If the goal is a team whose conventions survive across tools and people, the instruction file is the necessary first layer, not the whole answer: see [shared memory across coding agents](https://aq.dev/guides/shared-memory-across-coding-agents/) for what each harness remembers beyond this file, and [team memory for coding agents](https://aq.dev/guides/team-memory-for-coding-agents/) for the layer above it.

## Step 1: make AGENTS.md the only file humans edit

Pick AGENTS.md as the canonical file because it is the one every tool now agrees on. Put in it exactly what every agent needs in every session: build and test commands, project layout, naming conventions, and the "always do X" rules a new teammate would need. Keep it concise; Anthropic's guidance for CLAUDE.md (specific, verifiable instructions, kept short) applies equally well here, since Claude Code loads this file directly. Everything else in this guide exists to make sure no second file competes with this one.

## Step 2: decide whether Claude Code still needs a bridge

On Claude Code 2.1.277 or later, the default behavior (Anthropic calls the setting "Project instructions", value `claude-md-or-agents-md`) is:

| Your repository has | Claude Code reads |
| --- | --- |
| An AGENTS.md and no CLAUDE.md or CLAUDE.local.md in the working directory or above | Your AGENTS.md (every AGENTS.md and .claude/AGENTS.md up the directory tree, plus subdirectory AGENTS.md files as it reads code there) |
| Both an AGENTS.md and a CLAUDE.md (or CLAUDE.local.md) | Your CLAUDE.md files only |
| A CLAUDE.md that imports AGENTS.md with @AGENTS.md | Your CLAUDE.md, with AGENTS.md included through the import |

So if your repo has nothing genuinely Claude-specific, the cleanest setup is one AGENTS.md and no CLAUDE.md anywhere. In an interactive session you can confirm it loaded: Claude Code prints a line such as "no CLAUDE.md found; AGENTS.md loaded" at session start, and `/memory` lists the file's path (on versions before 2.1.280, `/memory` and `/context` did not list a directly read AGENTS.md; there, ask Claude what its project instructions say). One behavioral difference Anthropic documents: InstructionsLoaded hooks do not fire for an AGENTS.md read through the setting, though they fire as usual for one a CLAUDE.md imports or symlinks to. One documented gotcha: a personal, uncommitted CLAUDE.local.md counts as a CLAUDE.md for the precedence check, so adding one silently stops Claude Code from reading AGENTS.md for you alone. Also note the lookalike files Claude Code does not read: AGENTS.local.md, AGENTS.override.md (a Codex convention), and anything under a .agents/ directory.

If you want different behavior, `/config` exposes four Project instructions values as of October 2026: the default (CLAUDE.md, or AGENTS.md when no CLAUDE.md exists), `claude-md-and-agents-md` (both files, with each directory's CLAUDE.md first; an AGENTS.md already pulled in by an import or symlink is not read twice), `claude-md` (ignore AGENTS.md entirely), and `managed-only` (only an organization's managed instructions). Since version 2.1.285 the value can also live in a settings file: an entry under `pluginConfigs` keyed `cc-plugin-agents-md@builtin` (the ID of the built-in plugin that reads AGENTS.md; before 2.1.285 the key was `agents-md@builtin`, and current versions read either), honored in ~/.claude/settings.json, a --settings file, or an organization's managed settings. The catch for teams remains: Claude Code deliberately ignores that entry in project and local settings files, so you still cannot set it for everyone by committing a file to the repo. An organization that distributes managed settings can roll it out fleet-wide; everyone else needs the bridge below.

That is why the old bridge keeps a job. A CLAUDE.md whose first line is the import travels with the repository and gives every teammate the same result on any Claude Code version:

```
# CLAUDE.md
@AGENTS.md

## Claude Code specifics
Use plan mode for changes under src/billing/.
```

Use the import bridge when any of these hold: someone on the team runs a Claude Code version before 2.1.277 (or before 2.1.281 on Bedrock, Vertex AI, or an LLM gateway), or has turned off the built-in plugin that reads AGENTS.md via /plugin; you have genuinely Claude-specific instructions to add below the import; or you want both files loaded without asking every teammate to change a personal setting. The committed symlink (`ln -s AGENTS.md CLAUDE.md`) still works too, with the same caveat as always: on Windows, creating symlinks needs administrator privileges or Developer Mode, and a checkout without `core.symlinks` enabled produces a plain text file containing the literal path, so mixed-OS teams should prefer the import. Whichever bridge you choose, verify it in your next session with `/context`.

## Step 3: the trees that do not symlink

The single-file setup solves prose instructions. Three per-tool directory trees remain, and pretending they are one tree causes more pain than accepting a small amount of duplication.

**Skills mostly converge.** Claude Code loads skills from .claude/skills/ and Codex loads them from .codex/skills/ (project) or ~/.codex/skills/ (personal), and as of August 2026 both use the same layout: a folder per skill containing a SKILL.md with name and description frontmatter, plus optional scripts and references. Because the format is shared, a skill folder can be symlinked or copied between the two trees, and repo-level skills travel to everyone on clone. If your team keeps reusable workflows anywhere, keep them here.

**Commands and prompts do not.** Claude Code's custom slash commands live in .claude/commands/ inside the repo. Codex's equivalent, custom prompts in ~/.codex/prompts/, is personal rather than repo-shared, and OpenAI now marks custom prompts deprecated in favor of skills. The practical rule: put team workflows in skills, which both tools share and version, and treat slash commands as personal sugar.

**Rules stay per-tool.** Cursor's .cursor/rules/*.mdc files carry metadata and globs; Claude Code's .claude/rules/ files use paths frontmatter for the same job (and keep loading even when project instructions come from AGENTS.md). They do not map one to one, so keep them for genuinely path-scoped instructions ("all API handlers must validate input") and resist the urge to mirror universal conventions into them. Universal conventions belong in AGENTS.md, once.

## Step 4: clean up the old workarounds, then guard against drift

If you set Claude Code up to read AGENTS.md before it could do so on its own, Anthropic's memory documentation now says what to do with each workaround, as of October 2026:

**A CLAUDE.md containing @AGENTS.md:** safe to leave. The import is never loaded twice whichever Project instructions value anyone uses, and it keeps covering teammates on older versions. Delete the CLAUDE.md only if it holds nothing else and everyone is current. **A CLAUDE.md that tells Claude in words to "read AGENTS.md":** replace it with the import or delete it; a worded instruction only works if the model decides to open the file. **A symlinked CLAUDE.md:** keep or delete, either way the content loads once; note that Claude Code's editing tools refuse to write through a symlink and point at the target instead. **A SessionStart hook that prints AGENTS.md:** remove it, because once Claude Code reads the file directly the hook puts a second copy in the context.

Migration tooling helps in both directions: Claude Code's `/init` incorporates existing Cursor rules and Copilot instructions into the file it generates, its `/import` command (v2.1.213 and later) does a one-time copy of another agent's setup (AGENTS.md, commands, skills, MCP servers), and OpenCode's opencode.json accepts an instructions array that references existing files without duplicating them.

Then make regression impossible. With native support, the cheapest guard is structural: no CLAUDE.md in the repo at all, so there is nothing to drift. For repos that keep a bridge, a CI step that fails when CLAUDE.md stops being thin still earns its keep:

```
# ci: CLAUDE.md must stay a symlink or an AGENTS.md import
if [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then
  grep -q "@AGENTS.md" CLAUDE.md || {
    echo "CLAUDE.md must import AGENTS.md, not duplicate it"
    exit 1
  }
fi
```

Teams that must keep real copies (some hosted environments reject symlinks) should diff the copies in CI instead, and fail the build on divergence. Either way the property you are enforcing is the same: one file humans edit, everything else derived or deleted.

## Where AQ fits

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. The one-repo-many-CLIs situation this guide describes is AQ's normal operating mode: agents run as real CLIs (Claude Code, Codex, Cursor Agent, Kimi, Grok, or plain shells) in persistent tmux sessions on your team's VM, often several different CLIs against the same repository in the same week.

Two properties of that setup make the single-source-of-truth discipline pay off. First, every AQ workspace gets its own isolated git worktree on a fresh branch, with dependencies installed automatically, so whichever CLI a teammate launches reads the committed AGENTS.md (or its bridge, where one is still needed) exactly as it exists on that branch; there is no per-machine copy to go stale. Second, the sessions themselves are visible: teammates can open the same workspace and watch the same live session, so when an agent does ignore a convention, someone sees it in the transcript rather than discovering it in review. Sessions survive a closed laptop and resume from any device, each engineer signs into the CLIs with their own Claude or OpenAI account, and agents commit, push, and open PRs that AQ tracks per workspace.

AQ has two plans: Free is a personal sandbox for one person (AQ creates a private machine in an isolated network, nothing to install, no time limit), and AQ Pro is $50 per user per month in early access (standard $200, billed monthly, rate locked for your first 12 months) covering VMs you connect from your own cloud or a dedicated always-on AQ-managed VM. If your team is already juggling Claude Code and Codex against one repo, the setup in this guide works anywhere, and AQ is where it stops depending on every laptop being configured the same way. See also: [carrying context between Claude Code and Codex](https://aq.dev/guides/carry-context-between-claude-code-and-codex/) and [running multiple AI coding agents in parallel](https://aq.dev/guides/run-multiple-ai-coding-agents-in-parallel/).

## Frequently asked questions

### Does Claude Code read AGENTS.md?

Yes, as of version 2.1.277, released September 18, 2026. In a project with no CLAUDE.md or CLAUDE.local.md in the working directory or above it, Claude Code reads AGENTS.md (and .claude/AGENTS.md) as its project instructions automatically. When a CLAUDE.md exists too, Claude Code reads only the CLAUDE.md by default; the Project instructions setting in /config can change that. Version 2.1.281 extended the support to Amazon Bedrock, Google Vertex AI, LLM gateways, and sessions with telemetry disabled.

### Can Claude Code read both AGENTS.md and CLAUDE.md together?

Yes, three ways as of October 2026. Per person: set Project instructions to claude-md-and-agents-md in /config, which loads each directory's CLAUDE.md files first and its AGENTS.md after them, skipping any AGENTS.md already pulled in by an import. Per organization: ship the same value in managed settings under pluginConfigs (key cc-plugin-agents-md@builtin, Claude Code 2.1.285 and later). Per repository: put @AGENTS.md at the top of CLAUDE.md, which travels with the repo and works on every Claude Code version; the setting is ignored in project and local settings files, so a repo cannot commit it.

### Do I still need the @AGENTS.md import or a symlink?

Only in specific cases now: teammates on Claude Code versions before 2.1.277 (or before 2.1.281 on Bedrock, Vertex AI, or an LLM gateway), a repo that must keep a CLAUDE.md with Claude-specific content, or a team that wants both files loaded without everyone changing a personal setting. If you need a bridge, prefer the import over the symlink on any team with Windows machines, where creating symlinks requires administrator privileges or Developer Mode. An existing import is safe to keep: Claude Code never loads the file twice.

### Can I share one AGENTS.md across every coding agent CLI?

Yes, as of October 2026 a single AGENTS.md at the repository root is read natively by Claude Code (2.1.277 and later, when no CLAUDE.md exists), Codex, Cursor, OpenCode, GitHub Copilot, Grok CLI, Kimi CLI, and Google's Antigravity CLI, each verified on the vendor's own documentation. Cursor combines it with its .cursor/rules/*.mdc files, Codex concatenates a global ~/.codex file with per-directory AGENTS.md files, OpenCode falls back to CLAUDE.md only when no AGENTS.md exists, Copilot reads the nearest AGENTS.md alongside .github/copilot-instructions.md, Grok reads AGENTS.md and CLAUDE.md variants in every directory plus .grok/rules/, Kimi merges AGENTS.md from the project root down, and Antigravity reads AGENTS.md and GEMINI.md. What does not cross tools is personal global files and vendor auto memory, which stay per-person and per-tool.

### Why isn't Claude Code reading my AGENTS.md?

Check three things, in Anthropic's documented order as of October 2026. First, look for a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in your working directory or any directory above it: any one of them makes Claude Code read that instead, unless Project instructions is set to claude-md-and-agents-md. Second, run claude --version and confirm 2.1.277 or later (2.1.281 or later on Bedrock, Vertex AI, or an LLM gateway). Third, open /config and confirm Project instructions is not set to claude-md or managed-only; if the setting is missing entirely, your session cannot load AGENTS.md (old version, or the built-in plugin disabled), so bridge it with an @AGENTS.md import from a CLAUDE.md. One more documented case: in some sessions, the first session after upgrading from v2.1.276 or earlier still reads only CLAUDE.md files, and AGENTS.md loads from the next session on. Confirm the fix by running /memory and looking for the file's path.

### Does the Antigravity CLI (formerly Gemini CLI) read AGENTS.md or GEMINI.md?

Both, as of October 2026. Google's official migration guide says the Antigravity CLI (binary agy) reads the active directory's GEMINI.md and AGENTS.md files, and applies global rules from ~/.gemini/GEMINI.md across all workspaces. An existing Gemini CLI setup carries over with agy plugin import gemini. For a repository shared across tools, that means a GEMINI.md is no longer necessary: the AGENTS.md every other CLI reads covers Antigravity too, and GEMINI.md remains useful mainly for the personal global file.

### How do teams stop AGENTS.md and CLAUDE.md drifting apart?

Structurally where possible: with native support in every major CLI, a repo can keep one AGENTS.md and no CLAUDE.md at all, so there is nothing to drift. Where a CLAUDE.md must stay, keep it a symlink or a one-line @AGENTS.md import, and add a CI step that fails whenever CLAUDE.md is a regular file that does not contain @AGENTS.md. Where real copies are unavoidable, diff the copies in CI and fail on divergence. Drift is a process problem, so the fix belongs in the pipeline, not in a convention document.

---

About AQ: AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. Start at [aq.dev](https://aq.dev/).