One project. Claude Code and Codex.

A plain-English guide to setting up your project so Claude Code and Codex can both work from the same context. The same pattern can support other coding agents too.

1. The problem in 30 seconds

Every AI coding agent needs instructions, reusable workflows, and tool settings. 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: give each tool the files it expects, but keep your real project knowledge in shared folders like docs/, references/, and templates/.

2. How each tool organizes a project

Same idea, different file names and formats.

Claude Code

Anthropic's coding agent

One folder holds settings, agents, and skills.

Instructions

CLAUDE.mdSits at the project root. Loads automatically.

Config folder

.claude/Holds skills, agents, rules, and settings.

Skills

.claude/skills/<name>/SKILL.mdSlash commands you can build yourself.

Sub-agents

.claude/agents/<name>.mdMarkdown with a small YAML header on top.

Settings

.claude/settings.jsonHooks, permissions, env vars.

Global config

~/.claude/Same structure, but applies to every project on your machine.

Codex

OpenAI's coding agent

Config and agents live in .codex. Skills live in .agents.

Instructions

AGENTS.mdSits at the project root. Loads automatically.

Temp override

AGENTS.override.mdQuick way to override AGENTS.md without editing it.

Config folder

.codex/Holds config and agent definitions.

Skills folder

.agents/skills/<name>/SKILL.mdCodex scans from your current directory up to the repo root.

Sub-agents

.codex/agents/<name>.tomlTOML format, not markdown.

Settings

.codex/config.tomlSandbox, MCP servers, env vars, profiles.

Global config

~/.codex/ and ~/.agents/skills/

Global config and agents live in ~/.codex. Global skills live in ~/.agents/skills.

Global vs project: both tools support both. Global files live in your home folder and apply everywhere. Project files live inside one repo.

~/.claude/ mirrors .claude/. Codex splits global files: ~/.codex/ for config and agents, ~/.agents/skills/ for skills.

3. What it looks like in your folder

Claude keeps everything in one folder. Codex splits config and skills into two folders.

your-project/
  CLAUDE.md                # Claude instructions
  AGENTS.md                # Codex instructions
  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

Claude Code filesCodex filesShared (any tool)

4. The cheat sheet

When you forget where something lives, this table has the answer.

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
Scoped subfolder instructions	Nested CLAUDE.md	Nested AGENTS.md

5. Five things that trip up beginners

Worth reading before you start. These are the differences you can't paper over.

1. Both tools have skills, in different folders.

Claude reads from .claude/skills/. Codex reads from .agents/skills/. Same basic SKILL.md shape, but Claude-specific tool names or hooks may need small edits for Codex.

2. Different formats for agents.

A Claude agent is a .md file with a small YAML header. A Codex agent is a .toml file. The instructions inside are the same idea, just wrapped differently.

3. Settings files are not interchangeable.

You can't copy .claude/settings.json into .codex/config.toml. They're different formats and configure different things. Keep them separate.

4. Codex reads nested instructions.

Both tools support a CLAUDE.md or AGENTS.md inside a subfolder for scoped instructions. Codex chains them from the repo root down to your current directory. The closer file wins.

5. Sub-agents work differently.

Claude agents are markdown files. Codex agents are TOML files. The role prompt can be similar, but the wrapper and execution model are different.

Bonus: keep shared context out of tool folders.

Put reusable knowledge in docs/, references/, and templates/. Then both tools can read the same source instead of drifting apart.

6. The tool-agnostic setup

Split your project into three layers. Shared knowledge in one place, workflows in another, tool-specific config in their own folders.

The three-layer rule

Separate content this way and you never write the same thing twice.

1

Shared knowledge

Lives in references/, docs/, templates/. Any agent reads it. Don't duplicate.

2

Workflows (skills)

Same basic SKILL.md shape in two folders: .claude/skills/ for Claude, .agents/skills/ for Codex. Sync the files, then adapt tool-specific details if needed.

3

Tool-specific config

Stays in .claude/ and .codex/. These don't overlap. Don't try to merge them.

7. The fastest way to convert a Claude project

Open the Claude-built project in Codex and paste this prompt. Codex can create the adapter files for you.

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

Please inspect the project and create a Codex adapter setup.

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/.
 - Copy important Claude skills from .claude/skills/ into .agents/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.
 - Keep local overrides and secrets out of git.

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

The whole conversion idea: do not rebuild the project. Add a Codex layer beside the Claude layer.

8. How to maintain it

The setup only works if both tools stay in sync. These are the habits that matter.

When you update project instructions: keep CLAUDE.md and AGENTS.md aligned. Don't maintain two full copies. Pick one as the 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 can read the same source.