Run Claude Code and Codex from the Same Project Without Duplicating Everything

The problem with one-tool setups

Every AI coding agent needs instructions, reusable workflows, and tool settings — but each tool names those files differently. Claude Code looks for CLAUDE.md and .claude/. Codex looks for AGENTS.md, .codex/, and .agents/skills/.

The fix isn't maintaining two separate projects. It's giving each tool the adapter files it expects while keeping the actual project knowledge in shared folders (docs/, references/, templates/) that both tools read from the same source.

Cheat sheet — where each tool looks for things

bashCopy
What you need              | Claude Code                        | Codex
---------------------------|------------------------------------|-----------------------------------------
Project instructions       | CLAUDE.md                          | AGENTS.md
Project config folder      | .claude/                           | .codex/
Where skills live          | .claude/skills/<name>/SKILL.md     | .agents/skills/<name>/SKILL.md
Where sub-agents live      | .claude/agents/<name>.md           | .codex/agents/<name>.toml
Agent file format          | Markdown + YAML header             | TOML
Hooks / permissions / env  | .claude/settings.json              | .codex/config.toml
Personal / temp override   | CLAUDE.local.md                    | AGENTS.override.md
Global config              | ~/.claude/                         | ~/.codex/ + ~/.agents/skills/
User-wide instructions     | ~/.claude/CLAUDE.md                | ~/.codex/AGENTS.md

The three-layer rule

Split your project into three layers. Once organized this way, you never write the same thing twice.

• Layer 1 — Shared Knowledge: lives in references/, docs/, templates/. Any agent reads it. Don't duplicate these files per-tool.
• Layer 2 — Workflows (Skills): same basic SKILL.md shape in two folders — .claude/skills/ for Claude Code, .agents/skills/ for Codex. Sync the files, then adapt tool-specific details only where needed.
• Layer 3 — Tool-Specific Config: stays in .claude/ and .codex/ respectively. These don't overlap. Don't try to merge them.

What the folder structure looks like

bashCopy
your-project/
  CLAUDE.md          # Claude instructions
  AGENTS.md          # Codex instructions (adapter pointing at shared knowledge)
  README.md          # Human overview
  .claude/           # Claude settings, agents, skills
    settings.json
    agents/my-agent.md
    skills/my-skill/SKILL.md
  .codex/            # Codex settings and agents
    config.toml
    agents/my-agent.toml
  .agents/           # Codex skills
    skills/my-skill/SKILL.md
  references/        # Shared knowledge any agent can read
    project-context.md

5 things that trip up beginners

• Both tools have skills, in different folders — Claude reads from .claude/skills/, Codex reads from .agents/skills/. Same SKILL.md shape, but Claude-specific hooks may need small edits.
• Different formats for agents — Claude agents are .md files with a YAML header. Codex agents are .toml files. Same idea, different wrapper.
• Settings files are not interchangeable — .claude/settings.json and .codex/config.toml configure different things. Keep them separate.
• Codex reads nested instructions — both tools support a CLAUDE.md or AGENTS.md inside a subfolder. Codex chains them from the repo root down. The closer file wins.
• Sub-agents work differently — Claude agents are markdown. Codex agents are TOML. The role prompt can be similar, but the wrapper and execution model differ.

Convert a Claude project to Codex — use this prompt

Open the Claude-built project in Codex and paste this prompt. Codex creates all the adapter files in one pass without rebuilding the project.

promptCopy
I built this project in Claude Code and want it to also work well in Codex.

Please inspect the project and do these things:

1. Create AGENTS.md at the project root.
   - Use CLAUDE.md as the source of project knowledge.
   - Do not duplicate long sections unnecessarily.
   - Explain that AGENTS.md is the Codex-facing adapter.
   - Include a clear project map.

2. Create .codex/config.toml.
   - Start with a minimal safe config.
   - Do not add secrets.

3. Create .agents/skills/ by copying important Claude skills from .claude/skills/.
   - Keep each SKILL.md and supporting files together.
   - Do not put skills in .codex/skills/.

4. Create .codex/agents/ for any important Claude agents.
   - Claude agents are .md files in .claude/agents/.
   - Codex agents are .toml files in .codex/agents/.
   - Convert the agent instructions into developer_instructions.

5. Update .gitignore if needed to keep local overrides and secrets out of git.

Before editing, show me the files you plan to create or change.

The goal: add a Codex layer beside the Claude layer. Do not rebuild the project.

Maintenance habits that keep both tools in sync

• When you update project instructions: keep CLAUDE.md and AGENTS.md aligned. Pick one as source of truth and make the other an adapter.
• When you create a Claude skill: also copy it to .agents/skills/ if Codex should use it.
• When you create a Claude agent: also create a matching .codex/agents/<name>.toml if Codex should spawn it.
• When you add shared knowledge: put it in docs/, references/, or templates/ so every tool reads the same source.

Frequently asked questions

Do I need to maintain two full files indefinitely? No. One is the source of truth and the other is an adapter. If you keep your real project knowledge in CLAUDE.md, AGENTS.md can be a shorter file that points at it with Codex-specific framing. Only the adapter needs updates when the underlying knowledge changes.

What if I only ever use Claude Code? Only set this up if you plan to switch or run both tools. The three-layer structure doesn't hurt single-tool projects, but it does add files you won't use. If you're Claude-only, skip AGENTS.md and .agents/ and use the standard Claude structure.

Can the same skill file work in both tools without changes? Usually yes — SKILL.md files are plain markdown and both tools read them the same way. The only exceptions are lines that reference Claude-specific tools, hooks, or permissions blocks. Those need small edits for Codex.