Put your project's instructions in one AGENTS.md at the root of the repository. Codex reads it in every session, and Claude Code reads it too when the project has no CLAUDE.md (Claude Code 2.1.277 or later). If you want instructions only Claude should see, keep a CLAUDE.md that imports the shared file with @AGENTS.md. Your global rules can be shared 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 check what Claude loaded, run /context in a new session and look under Memory files.
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.
2. Where each agent looks
| Codex | Claude Code | |
|---|---|---|
| Global | ~/.codex/AGENTS.md (or AGENTS.override.md there) | ~/.claude/CLAUDE.md |
| Project | One file per folder, from the Git root down to the current folder: AGENTS.override.md, else AGENTS.md, else a fallback name | CLAUDE.md or .claude/CLAUDE.md; AGENTS.md when there's no CLAUDE.md |
| Subfolders | Folders between the root and where you are | A subfolder's file when Claude reads a file in that folder |
| Order | Root first, so the closest file wins | Imports expanded in place |
| Limit | 32 KiB combined by default (project_doc_max_bytes) | Up to four levels of imports |
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.
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.md4. 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.
Orbtile is building Shared Memory for this: one set of local sources you choose, which Claude Code and Codex both search and cite. It's in early access.
FAQ
Does Claude Code read AGENTS.md?
Yes, from version 2.1.277, when there's no CLAUDE.md in your working directory or above it. With a CLAUDE.md, import it with @AGENTS.md.
Can Codex read CLAUDE.md?
Yes, when you list it in project_doc_fallback_filenames. Codex then uses it in folders without an AGENTS.md.
Can I see both agents' sessions in one place?
Yes. Orbtile shows Claude Code and Codex sessions side by side on the Logitech MX Creative Keypad or an Android phone. See Run several Claude Code sessions at once and know which one needs you.