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

Published August 20, 2026 · by the AQ team

The reliable way to run several agent CLIs against one repository without instruction drift is to make AGENTS.md the only instruction file humans edit, bridge Claude Code to it with a one-line @AGENTS.md import (or a committed symlink), and treat the trees that genuinely cannot be shared (skills, commands, rules) as thin per-tool wrappers around that single source of truth. As of August 2026 that covers Codex, Cursor, OpenCode, GitHub Copilot, and most other coding agents natively, with Claude Code bridged by one line. This guide walks through the whole setup, the tradeoffs between the import and the symlink, and what to do with the directories that refuse to converge.

Why one repo ends up with three instruction files

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 the agents.md project counts over 60,000 repositories using it. Codex, Cursor, OpenCode, GitHub Copilot, Gemini CLI, Windsurf, and Zed all read it natively as of August 2026.

Claude Code is the notable holdout. Anthropic's own documentation is explicit: Claude Code reads CLAUDE.md, not AGENTS.md. The GitHub feature request to change that (anthropics/claude-code issue 6235) has over 5,200 thumbs-up reactions, making it the most upvoted request on the tracker, and as of August 2026 it is marked not planned. A claim that circulates in third-party guides, that Claude Code silently falls back to AGENTS.md when no CLAUDE.md exists, is not in the official documentation and does not match observed behavior. If your CLAUDE.md is missing, Claude Code simply starts without project instructions.

So a team running Codex and Claude Code side by side ends up with two files carrying the same build commands and conventions. The failure mode is predictable: someone fixes the test command in CLAUDE.md, AGENTS.md goes stale, and a week later Codex "ignores the conventions." It did not ignore anything. It read the other file.

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

Pick AGENTS.md as the canonical file because it is the one the most tools agree 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 (target under 200 lines, specific and verifiable instructions) applies equally well here, since a bridged Claude Code will load this file verbatim. Everything else in this guide exists to make the other files follow this one.

Step 2: bridge Claude Code with an import or a symlink

Anthropic documents two supported bridges, and both mean you never edit CLAUDE.md content again.

The import uses Claude Code's @path memory syntax. CLAUDE.md becomes two lines plus anything genuinely Claude-specific:

# CLAUDE.md
@AGENTS.md

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

Claude Code expands the import at session start and loads AGENTS.md as if it were written inline. Imports resolve relative to the importing file and can nest up to four hops deep, so an AGENTS.md that itself imports topic files still works.

The symlink suits repos with nothing Claude-specific to add:

ln -s AGENTS.md CLAUDE.md
git add CLAUDE.md

Git tracks symlinks natively, so teammates get the link on clone with no setup. The catch is Windows: creating a symlink there requires administrator privileges or Developer Mode, and checkouts on machines without either produce a plain text file containing the literal path. Anthropic's docs recommend the import on Windows for exactly this reason, and on a mixed-OS team the import is the safer default all around. Either way, verify the bridge in your next session: run /context in Claude Code and confirm CLAUDE.md appears under Memory files.

Step 3: the trees that do not symlink

The single-file bridge 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. 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: guard against drift, and migrate what exists

If your repo already has a real CLAUDE.md, fold its content into AGENTS.md and replace it with the bridge in one commit. Tooling helps in both directions: Claude Code's /init incorporates existing Cursor rules and Copilot instructions into the file it generates, its /import command 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. The cheapest guard is a CI step that fails when CLAUDE.md stops being a thin bridge:

# 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.

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 and its bridge exactly as they exist 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 Team 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 and running multiple AI coding agents in parallel.