Sync Claude Code and Codex Configs Without Drift (2026)

When you run Claude Code and Codex against the same repository, project instructions, skills, hooks, and MCP configs tend to fork by host.

📑Table of Contents

1. Config surface cheat sheet
2. Why dual-agent configs drift so quickly
3. Official load rules you must respect
4. Design patterns: unify, adapt, peer-audit, or tool-sync
5. Rollout checklist
6. Failure modes to avoid
7. FAQ
8. What to do next

Updating only one side leaves the other agent on stale rules. That is less a hype-cycle problem than a structural one: each product defines its own discovery paths and formats.

Learning outcomes

---

What this article covers

This article covers:

• Official load rules mapped side by side
• Four durable design patterns (single file, canonical-plus-adapter, peer files with audit, selective sync tools)
• A rollout checklist and FAQ

Popularity signals are discovery context only; facts come from vendor docs and independent write-ups.

---

Config surface cheat sheet

Instruction surfaces

Source

Surface	Claude Code	Codex	Sync reality
Project instructions	CLAUDE.md / .claude/CLAUDE.md	AGENTS.md (hierarchical discovery)	Different names and load order; naive copies drift
User / global instructions	~/.claude/CLAUDE.md	~/.codex/AGENTS.md (override wins)	Global peers need management too

---

Skills, config formats, and rules

Surface	Claude Code	Codex	Sync reality
Skills search paths	~/.claude/skills/ and related	~/.agents/skills/ and related	Symlink identical content; peer when wording must differ
Config formats	settings.json / .mcp.json	config.toml / hook configs	Convert formats or keep a thin adapter
Path rules	.claude/rules/	~/.codex/rules is approval policy (different job)	Do not sync as if equivalent

---

Sources and practical rule

Sources (as of July 2026):

• Anthropic Claude Code Memory
• OpenAI Codex AGENTS.md guide
• Qiita kirozero coexistence notes
• Explaza agents-sync write-up

Practical rule: sync surfaces that share meaning; leave deliberately different surfaces alone—especially Codex approval rules.

---

Why dual-agent configs drift so quickly

Both tools need project norms, personal skills, hooks, and MCP wiring, but they store them under different paths and DSLs.

Claude Code load assumptions

Human-authored CLAUDE.md loads managed → user → project → local.

• It is context, not enforced configuration
• Use PreToolUse hooks when you need hard blocks
• Keep files under roughly 200 lines
• @path imports go up to four hops

See Anthropic’s Memory docs.

---

Codex load assumptions

Discovery prefers at most one file per directory from repo root down to cwd, in this order:

1. AGENTS.override.md
2. AGENTS.md
3. Names listed in project_doc_fallback_filenames

Merged text is truncated by project_doc_max_bytes (default 32 KiB) (AGENTS.md guide).

---

Common incidents

1. Updating only one instruction file
2. Trusting mtime after git checkout rewrites timestamps
3. Syncing Codex approval rules as if they were Claude path-scoped rules

“Copy everything” without a surface map multiplies all three.

---

Official load rules you must respect

Claude Code

• Project files: ./CLAUDE.md or ./.claude/CLAUDE.md
• Personal local: CLAUDE.local.md (usually gitignored)
• Parent-directory memory loads at start; subdirectory files load on demand
• Relative @import paths resolve from the importing file; @ inside code spans/fences is not an import
• Push long procedures into skills or .claude/rules/; keep CLAUDE.md for always-on norms

Use session tools such as /context after sync to verify which memory files actually loaded.

---

Codex

• Global: under CODEX_HOME (default ~/.codex), override file wins over AGENTS.md
• Project: per directory, override → AGENTS.md → fallback names; merge root → cwd
• Alias files via project_doc_fallback_filenames (for example CLAUDE.md, README.md)

Classmethod’s independent guide documents project_doc_fallback_filenames = ["CLAUDE.md","README.md"] so teams can center on CLAUDE.md.

If AGENTS.md exists in the same directory, AGENTS still wins—fallback is not a silent override.

Gemini CLI can point context.fileName at CLAUDE.md, but this article focuses on Claude Code and Codex.

---

Design patterns: unify, adapt, peer-audit, or tool-sync

Pattern comparison table

Split by how much host-specific structure you keep.

---

Patterns A–B (unify or thin adapter)

Pattern	Canonical layout	Best when	Main constraint	Representative source
A. CLAUDE.md-centric	Codex fallback lists CLAUDE.md	You only need instruction parity	Sibling AGENTS.md still wins	classmethod
B. Canonical + thin adapter	AGENTS.md canonical; CLAUDE.md @AGENTS.md; skills from ~/.agents/skills via symlink	You accept coexistence with minimal forks	JSON/TOML hosts stay separate	Qiita kirozero

---

Patterns C–D (peer audit or selective tools)

---

Pattern C. Peer files + audit

Pattern	Canonical layout	Best when	Main constraint	Representative source
C. Peer files + audit	Parallel claude/ and codex/ trees symlinked live; manifest/pre-commit blocks drift	Teams must refuse one-sided commits	Visualization/refusal over auto-merge	stafforini

---

Pattern D. Selective sync tools

Pattern	Canonical layout	Best when	Main constraint	Representative source
D. Selective sync tools	agents-sync, ai-config-sync-manager, etc.	You already have drift and want item-level sync	Tooling cost; model-specific prompts	Explaza agents-sync, OpenAI Community thread

Sources: links in the table (public posts from March–July 2026).

---

Pattern notes

---

A. Instruction-only unification

• Stops double-editing instruction files
• Leaves skills/hooks/MCP forked

---

B. Canonical + thin adapter (kirozero)

• Keeps AGENTS.md as the rule source
• Imports it into Claude via @AGENTS.md
• Symlinks skills from a single tree (~/.agents/skills)
• Shares hook scripts without sharing host config files
• If Codex App’s “Import other agent setup” copies skills, re-home them to symlinks afterward

---

C. Peer files + audit (stafforini)

• Versions peer implementations and symlinks into ~/.claude and ~/.codex
• Rejects commits that update only one side (manifest / pre-commit / audit)
• Often leaves mutable settings.json unsymlinked while hook scripts stay tracked

---

D. Selective sync tools

DevsProtein/agents-sync (MIT; Explaza write-up):

• Symlink identical surfaces
• Normalize/compare different formats (MCP JSON vs TOML)
• Use fingerprints instead of mtime
• Require humans on dual edits
• Optionally watch on macOS via launchd
• Keep the tool out of the project tree so it does not become a self-sync target

Community ai-config-sync-manager emphasizes:

• status / diff / apply / backup
• Color-coded drift board (updated 2026-07-25)
• Surfaces including permissions

---

Decision shortcuts

• Instructions only → A
• Minimum coexistence branching → B
• Team drift refusal → C
• Recover existing forks with selective sync → D

Hybrids are normal (B for instructions, D for MCP). Document non-goals before automation.

Related guides:

• Claude Code Skills — skill authoring
• Claude Code Setup plugin — setup automation for hooks/MCP
• OpenAI Codex plugin for Claude Code — a different Claude↔Codex bridge

---

Rollout checklist

Steps

1. Inventory project and global CLAUDE.md, AGENTS.md, skills, hooks, and MCP on both hosts.
2. Pick pattern A–D (or a hybrid per surface).
3. Explicitly list non-synced surfaces (Claude path rules, model-specific prompting, Codex approval rules).
4. First pass: diff → human merge → apply. Never assume one-way copy is safe.
5. Make it durable with symlinks, peer audit, or a selective watcher—not mtime sync.
6. Verify by running the same task on both hosts and checking which instructions/skills loaded.
7. Promote repo-canonical vs personal-local boundaries and any pre-commit/audit hooks to the team.

---

Checkbox form

• ✓ One canonical instruction lineage is chosen
• ✓ Sync targets (instructions / skills / hooks / MCP) are listed
• ✓ Non-targets (approval policy, etc.) are documented
• ✓ Dual-edit merge steps exist
• ✓ Both CLIs were verified after enablement

---

Operational rules

Also keep these operational rules in mind:

• Never put secrets in instruction files
• Do not vendor the sync tool into a path that becomes a sync target
• Re-check official byte limits and fallbacks at install time

---

Failure modes to avoid

Failure mode table

Failure	Why it happens	Mitigation
Syncing ~/.codex/rules to Claude rules	Approval policy ≠ instruction rules	Exclude from sync map
Editing only fallback CLAUDE.md while AGENTS.md exists	AGENTS wins in-directory	Fix priority or delete the stale winner
Mechanically syncing every skill	Prompting guides differ by model	Sync shared procedures only
mtime as source of truth	Checkout rewrites timestamps	Fingerprints / content diff / human merge
CLI-only guidance	Desktop app users skip inventory	Include both UIs in the surface map

---

Takeaway

Most failures start from “make everything identical.” Prefer identical meaning on shared surfaces, not byte-identical trees everywhere.

---

FAQ

Q1. Is teaching Codex to read CLAUDE.md enough?

A. For instructions, fallback filenames help—but a sibling AGENTS.md still wins. Skills, hooks, and MCP stay on separate paths, so it is rarely “enough” alone.

---

Q2. @AGENTS.md import versus peer files?

A. Import collapses Claude onto one canonical file. Peers allow host-specific wording (import syntax, tone) while audits keep meaning aligned. Choose import for minimalism, peers when teams must edit both shapes.

---

Q3. agents-sync versus ai-config-sync-manager?

A. Compare along these axes:

• agents-sync: symlink + format conversion + item selection + optional macOS residency
• Community manager: bidirectional status/diff/apply and a visual drift board
• OS fit, required surfaces (including permissions), and existing stack

Both assume preexisting drift.

---

Q4. Must every skill match byte-for-byte?

A. Shared procedures: one canonical tree + symlinks. Model-specific prompting: leave unsynced or peer-optimize.

---

Q5. What if you exceed official size guidance?

A. Size limits differ by host:

• Codex truncates merged project docs at project_doc_max_bytes (default 32 KiB)
• Long Claude memory burns context and reduces compliance—split into rules/skills and keep CLAUDE.md near the ~200-line guidance

---

What to do next

Drift is structural because discovery differs by product.

1. Pick pattern A–D
2. Freeze sync versus non-sync surfaces in a checklist
3. Converge once with diff/merge tooling or humans
4. Keep parity with symlinks, audits, or selective watchers

Perfect full automation is less valuable than boundaries that make silent one-sided edits hard.

Next actions:

1. Inventory both hosts
2. Choose a pattern
3. Validate on one project
4. Promote to team policy

For multi-agent workspace layout, see also wmux.

Related articles:

• 13626
• 13580
• 13621