Skip to content
RuleSellBeta
Sign up

Topic · A5

How to run Codex and Claude Code on the same project

A practical setup for using OpenAI Codex and Claude Code together: shared instructions, clean handoffs, and when each tool earns the keyboard.

Run Codex and Claude Code together by sharing project rules, separating active edits, and making handoffs explicit instead of improvising them mid-session.

The main mistake teams make is treating this as a model comparison. It is not. The practical question is whether your repo gives both tools the same baseline context, and whether your workflow makes it obvious who is doing what. Codex starts by loading AGENTS.md instructions in a defined chain from the repo root down to your current directory, with nearer files overriding earlier ones (OpenAI Codex docs). Claude Code starts with CLAUDE.md, project rules, and memory files that apply to the current session and working tree (Claude Code memory docs). If those two instruction layers disagree, the tools do not "average out." They diverge.

That is why the setup matters more than the model choice. A clean dual-tool repo has one canonical set of project-wide rules, one place for tool-specific extras, and one rule for concurrent edits.

Start with a shared instruction layer

Codex is strict about where it discovers project guidance. It looks for AGENTS.override.md, then AGENTS.md, then any configured fallback filenames in each directory it walks from the project root to the current directory (OpenAI Codex docs). Claude Code is different: it treats CLAUDE.md as persistent project context and lets you split bigger rule sets into .claude/rules/ files with narrower scope (Claude Code memory docs).

My recommendation for a repo that really uses both:

  1. Put tool-neutral project rules in AGENTS.md.
  2. Keep CLAUDE.md short and mostly Claude-specific.
  3. Move repeated multi-step workflows out of both files and into skills.
That gives you a clean split:
  • AGENTS.md holds stack, commands, testing expectations, style constraints, repo layout, and "never do this" rules.
  • CLAUDE.md holds Claude-only notes such as hook conventions, subagent preferences, or how your team uses Claude's memory and rules system.
  • SKILL.md folders hold reusable workflows like code review, migration playbooks, or deployment checklists.
This is partly a docs-backed fact and partly an operational recommendation. The docs confirm that Codex is AGENTS-first (OpenAI Codex docs) and Claude is CLAUDE-first (Claude Code memory docs). The recommendation is the least fragile way to stop them from drifting.

Skills are portable, but the install paths are not

This is the second place teams trip over themselves. Claude Code reads project skills from .claude/skills//SKILL.md and personal skills from ~/.claude/skills//SKILL.md (Claude Code skills docs). Codex reads skills from .agents/skills in the repo chain and from ~/.agents/skills, and it explicitly supports symlinked skill folders (OpenAI Codex skills docs).

That means the content format is shared, but the default discovery paths differ. If you are dual-wielding these tools, either:

  • author once in a neutral repo directory and install/symlink into both locations, or
  • keep repo-level portable skills in .agents/skills and expose them to Claude through a mirror or symlink strategy.
Do not write the same skill twice. One SKILL.md with two slightly different descriptions is enough to create mysterious behavior differences six weeks later.

Use handoff patterns, not ad hoc switching

The question is not "which tool is smarter." The question is "what kind of task am I holding right now?"

The handoff patterns that work in real repos usually look like this.

1. Codex scouts, Claude consolidates

Codex is good when you want a tight implementation loop grounded in repo instructions and a narrow task. Ask it to inspect the target files, propose a patch, and make the first pass. Then hand the resulting diff to Claude Code for the wider verification loop: test strategy, regression review, path-specific rules, and any subagent-based deep reading.

This pattern fits feature work where the code change is straightforward but the risk lives in the surrounding system.

2. Claude explores, Codex finishes

Claude Code has a stronger documented story for multiple parallel sessions and subagents. Anthropic explicitly recommends running multiple Claude sessions in parallel and using subagents for isolated research or heavy file-reading tasks (Claude Code best practices, Claude Code subagents docs). Use that when the task starts as exploration: architecture audit, dependency cleanup plan, or "find every place this assumption leaks." Once the shape is known, hand the tight implementation back to Codex.

This pattern fits refactors where discovery is the expensive part and editing is the cheap part.

3. Claude reviews, Codex keeps shipping

If you want one agent moving the branch forward while another checks safety, keep the roles separate. Claude subagents can run in their own context windows and return only the summary, which makes them useful for sidecar reviews without cluttering the main thread (Claude Code subagents docs). In practice, that means you can leave Codex on the implementation branch while Claude reviews the changed files for security, architecture drift, or missing tests.

4. Separate worktrees for parallel edits

If both agents are writing at once, use separate git worktrees. This is not because either CLI is broken. It is because concurrent autonomous edits in one filesystem tree create merge ambiguity you could have avoided. Claude's own docs call out memory and behavior that are scoped per working tree (Claude Code memory docs). OpenAI's public Codex product material also emphasizes worktrees for parallel agent work (OpenAI Codex page).

You can get away without worktrees for short, supervised edits. For anything longer than that, isolate.

Know what each tool is better at

You do not need fake certainty here. The honest answer is task-shaped.

Claude Code has the stronger documented harness for parallelism and deterministic control. Subagents isolate context. Hooks let you run commands at specific lifecycle events and enforce checks outside the model's discretion (Claude Code hooks guide, hooks reference). If a task benefits from sidecar reviewers, automatic validation, or long multi-branch exploration, Claude has the better documented machinery.

Codex has the cleaner AGENTS-driven instruction stack and an explicit repo-scoped skill model built around .agents/skills (OpenAI Codex docs, Codex skills docs). If your team cares about one portable instruction surface that can survive tool churn, Codex aligns better with that direction today.

That is why senior teams end up using both. One is often the better exploration harness. The other is often the cleaner portable-config harness.

What to do when both AGENTS.md and CLAUDE.md are present

If both files exist, assume each tool will privilege its own file. That means you need a policy.

The policy I would use:

  1. AGENTS.md is canonical for project-wide engineering rules.
  2. CLAUDE.md only adds Claude-specific workflow notes.
  3. Any duplicated rule must be machine-checked for drift or deliberately generated from one source.
A simple example:
  • AGENTS.md: "Run pnpm test after changing business logic. Prefer pnpm. Never rewrite migrations."
  • CLAUDE.md: "Use hooks to block edits to generated files. Route deep security review to the security-reviewer subagent."
That division keeps the neutral rules neutral and the tool-specific rules local to the tool that can actually use them.

Where this fails

The weak point is not the tools. It is instruction drift. If AGENTS.md says one thing and CLAUDE.md says another, you have built two different repos.

The second weak point is shared write access. Two autonomous sessions editing the same files in one tree is not "parallelism." It is delayed merge conflict.

The third weak point is overfitting workflows to one agent's features. A repo that only works when Claude hooks fire or only works when Codex skills are installed is not really multi-tool. The portable layer has to stay portable.

The fourth weak point is social, not technical. If the team cannot explain, in one sentence, why a task belongs in Codex instead of Claude Code, the workflow will decay into personal preference and folklore.

What to read next

Sources

Related GitHub projects

@anthropics

claude-code

Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explaining complex code, and handling git workflows - all through natural language commands.

⭐ 122,880

Frequently asked

Can Codex and Claude Code work in the same repository without conflicts?
Yes, if you separate their instruction layer and their active work. Codex reads AGENTS.md files in a root-to-current-directory chain, while Claude Code reads CLAUDE.md files and related project memory. The conflict risk is not the tools; it is humans letting those files drift.
Should AGENTS.md or CLAUDE.md be the canonical file?
If your team is truly multi-tool, make AGENTS.md the canonical project-wide rules file and keep CLAUDE.md short and Claude-specific. If you are Claude-first and only occasionally use Codex, the inverse can be fine, but you still need one source of truth.
When should I hand a task from Codex to Claude Code?
Hand off when the task benefits from long-running review loops, multiple parallel sessions, or Claude-specific hooks and subagents. Keep Codex on the tighter implementation loops where AGENTS.md guidance and explicit skills are enough.
Do both tools read SKILL.md?
Yes, but not from the same default path. Claude Code reads skills from .claude/skills and personal ~/.claude/skills locations. Codex reads skills from .agents/skills in the repo chain and from ~/.agents/skills. The SKILL.md format is portable; the install path is not.
What happens if AGENTS.md and CLAUDE.md disagree?
Each agent follows the file it actually loads, so disagreement becomes behavior drift. Treat that as a bug. Shared rules should live in one canonical file, with the other file only adding tool-specific details.
Do I need separate git worktrees?
Not always, but separate worktrees are the safer pattern for two live autonomous sessions making edits at the same time. If both agents are only reading, one worktree is fine. If both are editing, isolate them.

Related topics