Start a team

How to keep CLAUDE.md and AGENTS.md in sync

Last updated: 23 September 2026

Claude Code reads CLAUDE.md. Codex reads AGENTS.md. Use both agents on one repository and you have two files saying the same things, until one of them is edited and the other is not. Here is who reads what, three ways to keep a single source, and what flanner writes into both.

Who reads what

Claude Code

  • CLAUDE.md files, joined together: managed policy, your user file at ~/.claude/CLAUDE.md, the project's CLAUDE.md or .claude/CLAUDE.md, and a git-ignored CLAUDE.local.md.
  • Files in the working folder and every folder above it load at launch. Files in subfolders load when Claude reads something in that subfolder.
  • Since v2.1.277, AGENTS.md too, but only when no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md exists in the working folder or above it. The Project instructions option in /config changes that.
  • Never AGENTS.override.md, AGENTS.local.md, or anything under .agents/.

Codex

  • Your global file in ~/.codex: AGENTS.override.md if it exists, otherwise AGENTS.md.
  • Then one file per folder, from the git root down to the working folder: AGENTS.override.md, else AGENTS.md, else any fallback names you configure. They are joined root first, so the closer file comes later. Folders below the working folder are not read.
  • Reading stops at project_doc_max_bytes, 32 KiB by default.

Three ways to keep one source

1. Import AGENTS.md into CLAUDE.md

Make AGENTS.md the file you edit, and start CLAUDE.md with an import. This is what Claude Code's documentation recommends. Anything only Claude should see goes below the import:

@AGENTS.md ## Claude Code only - Use plan mode for changes to auth.

An import never loads the same file twice, and it works on every operating system. The repository behind this website does exactly this: its CLAUDE.md is one line.

2. A symlink

ln -s AGENTS.md CLAUDE.md

One file, two names. It works on macOS and Linux. The docs advise the import instead if anyone on the project uses Windows, where symlinks in a checkout are unreliable.

3. AGENTS.md alone

With no CLAUDE.md at all, current Claude Code reads AGENTS.md by itself. It is the least to maintain, but the documentation lists cases where it does not happen: on Amazon Bedrock and other third-party providers, with telemetry turned off, and in the first session after an upgrade. The import has none of those gaps.

Keep both files short

Codex stops reading at 32 KiB by default, and every line in these files is read at the start of every session. Keep them to what an agent must know in every task, and move the rest into skills, which load only when they are used, or into docs the files point to.

What flanner writes into both

flanner init writes the same block into CLAUDE.md and AGENTS.md, between <!-- flanner:managed v2 --> and <!-- /flanner:managed -->. It tells either agent where plans live and which MCP tools save them, to recall memory at the start of a task, and to check which copy of a skill loads before editing one.

  • Running flanner init again replaces only that block. Your own text above and below it is left alone, and a missing file is created.
  • flanner doctor reports a block written by an older version. It cannot tell whether someone edited the block by hand, so edit outside the markers.
  • If your CLAUDE.md imports AGENTS.md, Claude reads the block twice, once from each file. The copies are identical, so the cost is a few hundred tokens rather than a conflict.

What flanner init registers lists every file it writes for each agent.

Sources

Checked on 23 September 2026, against Claude Code v2.1.280.

← All posts