# How do you run Claude Code and Codex together on one project?

Date: 2026-06-06 · Author: Robert Scales · https://guidetoartificialintelligence.com/en/learn/run-claude-code-codex-together-project/

**Answer:** Give both agents one set of project rules in an AGENTS.md file, which Codex reads directly and Claude Code reads through a one-line CLAUDE.md import, then give each agent its own branch in its own git worktree. Assign tasks that touch different files, and merge their work one at a time after tests pass.

Claude Code, from Anthropic, and Codex, from OpenAI, are both **coding agents**: tools that read your project, edit files and run commands such as tests on their own. You might want to use both, for example one for a large refactor and the other for a batch of small fixes, or simply to compare approaches. Running them side by side on the same project works well, but only if they share the same rules and never edit the same files at the same moment.

Three pieces make that happen: one instructions file both agents read, a separate working folder for each agent, and a task split you decide before they start.

## Step 1: one instructions file for both agents

Each agent loads a Markdown file of project instructions at the start of a session. Codex reads **AGENTS.md**; OpenAI's documentation says it reads these files before doing any work, combining a personal file in `~/.codex` with any AGENTS.md files from the repository root down to the folder you are working in. Claude Code reads **CLAUDE.md** instead. Anthropic's documentation addresses exactly this situation: if a repository already has an AGENTS.md, create a CLAUDE.md that imports it with the line `@AGENTS.md`, so both tools load the same text. Anything Claude-specific can go below the import.

A shared AGENTS.md for a small web shop might look like this:

```markdown
# AGENTS.md
## Project
Online shop: Node.js API in api/, React front end in web/.

## Rules for every agent
- Run `npm test` before every commit. Never edit or delete existing tests to make them pass.
- Ask before adding any new dependency.
- Work only on your own branch. Never merge or push to main.
- Never edit files outside the folders named in your task.
- Write a one-paragraph summary of what you changed at the end.
```

And the whole CLAUDE.md:

```markdown
@AGENTS.md

## Claude Code only
Use plan mode before changing anything in api/payments/.
```

Keep the shared file short and concrete. Anthropic suggests staying under about 200 lines and writing rules that can be checked ("Run npm test before committing" rather than "test your changes"), and warns that when two rules contradict each other, the agent may pick either one. Codex caps the combined instructions at 32 KiB by default, so length matters there too.

## Step 2: give each agent its own worktree

If both agents work in the same folder, one can overwrite a file the other is halfway through editing, or run tests against a half-finished change. The fix is a **git worktree**: a second (or third) working folder attached to the same repository, each with its own branch and its own copy of the files, while sharing one history. Anthropic's best-practice guide recommends worktrees for running several Claude sessions at once, and the same approach works for mixing tools.

From the main project folder:

```bash
# One folder and one branch per agent
git worktree add ../shop-claude -b claude/checkout-form
git worktree add ../shop-codex  -b codex/order-history-api

# Terminal tab 1
cd ../shop-claude && claude

# Terminal tab 2
cd ../shop-codex && codex
```

Each agent now sees a complete project, works on its own branch and cannot touch the other's files. When a task is merged, remove its folder with `git worktree remove ../shop-claude`.

## Step 3: check that both agents loaded the rules

Before giving real work, confirm the shared file is active. In Codex, OpenAI documents a quick check: ask it to summarize the current instructions, and it should quote your AGENTS.md. In Claude Code, ask the same question at the start of a session. If either agent misses a rule, the file is in the wrong place or the import line is wrong, and it is far cheaper to find that out now.

> **Try it:** In a test repository, create the AGENTS.md and CLAUDE.md above, add one unusual rule (for example, "end every commit message with [shared-rules]"), give each agent a small task in its own worktree, and check both commit messages. If both carry the tag, the shared rules are working.

## How do you split work so they don't collide?

Split by files, not by feature names. Two tasks that sound separate, such as "add order history" and "fix checkout totals," can both touch the same pricing module. Before starting, write a short table that names, for each agent, the folders it may change:

| Agent | Branch | Task | May edit | Must not edit |
|---|---|---|---|---|
| Claude Code | claude/checkout-form | New checkout form with address validation | web/checkout/ | api/, package.json |
| Codex | codex/order-history-api | Order history endpoint and its tests | api/orders/, api/tests/orders/ | web/, package.json |

Paste each row into that agent's first message. Keep shared files, such as the dependency list (`package.json`), database schema or global styles, off-limits to both, and change them yourself in a separate step. Those files cause most of the conflicts because everything depends on them.

Merge one branch at a time. Run the full test suite on the first branch, merge it into main, then update the second branch from main and test again before merging. If the second merge reports a conflict, that is useful information: the split overlapped, so resolve it by hand and tighten the table next time.

Finally, review both agents' work the same way, whichever tool wrote it. The shared AGENTS.md sets the same expectations for both, which also makes their results easy to compare: when one consistently finishes a kind of task with fewer corrections, give it more of that kind.

## Sources

- How Claude remembers your project (Claude Code memory): https://code.claude.com/docs/en/memory
- Custom instructions with AGENTS.md: https://developers.openai.com/codex/guides/agents-md
- Claude Code: Best practices for agentic coding: https://www.anthropic.com/engineering/claude-code-best-practices