Share context between Claude Code and Codex

Share project context between Claude Code and Codex with one AGENTS.md at the repository root. Codex reads it every session; Claude Code 2.1.277 or later reads it when no CLAUDE.md exists. For Claude-only instructions, use a CLAUDE.md that imports @AGENTS.md. You can share global rules the same way, by importing Codex's global file into Claude's.

1. One instructions file for the project

If you only need shared instructions, an AGENTS.md alone is enough. Claude Code loads every AGENTS.md from your working directory and the directories above it at the start of a session, as long as none of them has a CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md.

If Claude needs extra instructions, keep AGENTS.md as the shared file and add a CLAUDE.md next to it that imports it:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

A symlink (ln -s AGENTS.md CLAUDE.md) also works on a Mac or Linux. On Windows, use the import: a symlink needs administrator rights or Developer Mode there, and Git checks it out as a plain text file unless core.symlinks is on.

To set up OpenAI's terminal agent in PowerShell or WSL2 first, see Install Codex CLI on Windows: PowerShell, npm, sandbox and WSL.

To check what Claude loaded, run /context in a new session and look under Memory files.

If you are moving from Cursor or running both tools together, see Cursor vs Claude Code: differences and how to use both for how /init and /import cursor carry over your rules.

When a section of CLAUDE.md grows into a repeatable procedure that should load only when needed, move it into a skill with Claude Code skills: SKILL.md, bundled skills and frontmatter.

If the project already has a CLAUDE.md and no AGENTS.md, Codex can read it: add this to ~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md"]

Codex then uses CLAUDE.md in any folder that has no AGENTS.md.

For the rest of the Codex CLI's setup, including installation, config.toml precedence, codex exec and sandboxing, see OpenAI Codex CLI: install, commands, config.toml and codex exec.

To connect external documentation and tools in the same configuration file, see Codex MCP servers: setup, CLI, config.toml and OAuth.

To upgrade your CLI release or check which installation is on your PATH, see Update Codex CLI and check the version.

When you run both agents in the same repository at once, isolate their file edits with Git worktrees for parallel coding agents: Claude Code and Codex.

2. Where each agent looks

Claude Code doesn't read AGENTS.override.md or AGENTS.local.md. If a project has both a CLAUDE.md and an AGENTS.md, Claude reads only CLAUDE.md by default. Import AGENTS.md from it, or set Project instructions to claude-md-and-agents-md in /config.

For how OpenCode and Claude Code each read AGENTS.md and CLAUDE.md, see OpenCode vs Claude Code: AGENTS.md, providers and setup.

3. Share your global rules too

Your personal rules live in two places: ~/.codex/AGENTS.md for Codex and ~/.claude/CLAUDE.md for Claude Code. Keep them in the Codex file and import it from Claude's:

@~/.codex/AGENTS.md

4. Share what they learn while working

Instructions tell both agents how to work; they don't carry over what one session found out. A plain notes file does: add a line like this to AGENTS.md,

Before you start, read docs/NOTES.md. When you make a decision someone will need later, add one line to it with the date.

and both agents read and add to the same record. Keep it short; it's loaded or read like any other file.