AGENTS.md vs CLAUDE.md

The file is easy to copy. The behavior around it is the migration.

Claude Code and Codex both use repository instructions, but they load and surround those instructions differently. A useful migration does more than rename CLAUDE.md to AGENTS.md.

The first-party Codex import flow should be the first pass. This page is the second-pass audit: what changed, what still enforces behavior, and what became advisory text.

What each file is doing

CLAUDE.mdClaude Code memory and instruction files can layer through the directory tree, local files, rule directories, and managed policy locations.

AGENTS.mdCodex uses AGENTS.md as repository guidance for codebase navigation, testing, conventions, and PR behavior within scoped directory trees.

The migration risks

1. Scope may change.

A nested instruction file can mean different things depending on how the target harness discovers and prioritizes it. Validate which files apply before Codex touches a subtree.

2. Rules can become weaker.

Some Claude Code behavior is enforced through settings, hooks, or managed configuration. Moving the wording into AGENTS.md may preserve intent without preserving enforcement.

3. Local notes can leak into active guidance.

Session logs, handoffs, and memory files may help continuity. They should not automatically become active instructions unless that is deliberate.

4. Tool references need translation.

MCP servers, skills, plugins, and shell commands often need target-specific wrapper formats. The instruction file can describe them, but the runtime config still has to be valid.

Local migration flow

curl -fsSL https://bringyour.ai/install.sh | sh
bringyour preview --from claude-code --to codex
bringyour migrate --from claude-code --to codex --policy merge

Bring Your AI leaves the source harness unchanged, writes merge-first target output, and records non-equivalent pieces as validation notes. The paid CLI runs locally. The remote MCP at bringyour.ai/mcp is no-data and only exposes discovery and install handoff tools.

Buy lifetime access Read the import checklist

Sources: OpenAI Codex switch page; OpenAI Codex AGENTS.md notes; Claude Code memory docs.

← back to bringyour.ai