Syncing Claude Code and Codex Projects
Nate Herk | AI Automationgo watch the original →
the gist
You can run Claude Code and Codex on the same project by mapping their specific file naming conventions and folder structures, allowing you to switch agents when one gets stuck.
Project Structure Mapping
Claude Code and Codex share the same underlying project files but require different configuration naming conventions. Claude Code expects a .claude folder for settings and a claude.md file for instructions, while Codex uses a .codex folder and an agents.md file. To make a project compatible with both, maintain both configuration files in the root directory. While skill files (markdown with YAML front matter) are cross-compatible, agent definitions differ in format: Claude Code uses markdown files, whereas Codex uses TOML files.
Automated Conversion
Instead of manual migration, use an LLM to generate the necessary configuration files. Provide the following prompt to either agent to initialize the secondary tool's structure:
I built this project using Claude Code, but I need Codex to be able to use it too. Create an agents.md file using my claude.md as inspiration. Create a .codex config folder, move all skills into an agents folder, and place all agents in a .codex folder. Perform research on the Codex and Claude Code documentation to ensure all important settings convert correctly.
Workflow Integration
To maintain consistency across agents, treat the project as a three-layer system consisting of shared knowledge (archives, reference files), skills (reusable workflows), and tool-specific configurations. When switching between agents, use a "session handoff" summary to capture active files, current decisions, and next steps. This allows you to paste the context into the second agent to resume work immediately if the first agent hits a bottleneck. Note that Codex sub-agents require explicit invocation, unlike Claude Code's automated handling.