Tool-Agnostic Setup

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.

1The 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/.

Diagram: Claude Code + Codex → shared project files

Both tools can use the same project knowledge. They just need different adapter files.

2How Each Tool Organizes a Project

Same idea, different file names and formats. Here's what each tool expects.

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 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/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.

3What It Looks Like in Your Folder

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

Claude Code

your-project/
  CLAUDE.md
  .claude/
    settings.json
    agents/
      researcher.md
    skills/
      youtube-video/
        SKILL.md

Codex

your-project/
  AGENTS.md
  .codex/
    config.toml
    agents/
      researcher.toml
  .agents/
    skills/
      youtube-video/
        SKILL.md

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 files Codex files Shared (any tool)

4The 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`

55 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.

6The 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.

Shared Knowledge

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

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.

Tool-Specific Config

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

7The Fastest Way to Convert a Project

Pick your direction. Open the project in the target tool and paste the prompt — it will create all the adapter files for you.

Open your Claude Code project in Codex and paste this prompt.

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 in TOML format. 5. Update .gitignore if needed. - Keep local overrides and secrets out of git. - Add AGENTS.override.md to .gitignore. 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.

Open your Codex project in Claude Code and paste this prompt.

I built this project in Codex and want it to also work well in Claude Code. Please inspect the project and create a Claude Code adapter setup. Do these things: 1. Create CLAUDE.md at the project root. - Use AGENTS.md as the source of project knowledge. - Do not duplicate long sections unnecessarily. - Explain that CLAUDE.md is the Claude-facing adapter. - Include a clear project map showing where everything lives. 2. Create .claude/settings.json. - Start with a minimal safe config: empty permissions, hooks, and env objects. - Do not copy secrets or API keys from .codex/config.toml. 3. Create .claude/skills/ from .agents/skills/. - Copy each skill folder from .agents/skills/ into .claude/skills/. - Keep each SKILL.md and any supporting files together. - Claude skills are triggered as slash commands — note this in each SKILL.md if it isn't already. 4. Create .claude/agents/ from .codex/agents/. - Codex agents are .toml files in .codex/agents/. - Claude agents are .md files in .claude/agents/. - Each Claude agent needs a small YAML front matter block at the top: --- name: Agent Name description: One-line description of what this agent does --- - Move the developer_instructions content into the markdown body below the front matter. 5. Update .gitignore if needed. - Add CLAUDE.local.md so personal overrides stay out of git. - Keep .env and any credential files gitignored. Before editing, show me the files you plan to create or change.

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

The key differences: Claude agents are .md files with a YAML header, skills live in .claude/skills/ not .agents/skills/, and settings are JSON not TOML.

8How 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. Do not 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.