How to run Claude Code and Codex together

To run Claude Code and Codex together, give each agent its own git worktree and branch, share one set of project instructions between them, pass work from one to the other with a written handoff note, and review every diff before it is merged. The most reliable patterns are one implements while the other reviews, and one investigates while the other implements.

Why use both

Developers who use both agents usually do so for practical reasons: a second agent is a cheap second opinion, each has tasks its users prefer it for, and two agents can work on separate tasks at the same time. The cost is coordination. Without some structure you spend your time copying context between terminals and untangling conflicting edits.

Step 1: Give each agent its own worktree

Never point two agents at the same working directory. A git worktree gives each agent a separate checkout of the same repository on its own branch, so their edits cannot overwrite each other:

# from your main checkout
git worktree add ../myapp-claude -b claude/investigate-retry
git worktree add ../myapp-codex  -b codex/fix-retry

# run each agent in its own directory
cd ../myapp-claude && claude
cd ../myapp-codex  && codex

When a task is done, merge or rebase the branch as you would a teammate’s, then remove the worktree with git worktree remove.

Step 2: Share one set of project instructions

Both agents read a project instructions file at the start of a session: Codex reads AGENTS.md and Claude Code reads CLAUDE.md. Keep one source of truth so they follow the same rules. A simple approach is to write the instructions in AGENTS.md and import that file from CLAUDE.md:

# CLAUDE.md
@AGENTS.md

Put the things both agents must respect there: how to run the tests, code style, directories not to touch, and decisions that are already settled.

Step 3: Pick a collaboration pattern

Pattern A: one implements, the other reviews

One agent writes the change on its branch. The other agent, in its own worktree, reviews the diff against the original goal and looks for missed edge cases. You decide what to accept. This catches a surprising number of confident mistakes, because the reviewer did not write the code.

Pattern B: one investigates, the other implements

One agent explores the codebase and writes up the cause of a bug and the constraints a fix must keep. The other agent receives that write-up and implements the fix. Splitting the work keeps each session focused and gives you a written record of why the change was made.

Pattern C: separate tasks in parallel

Give each agent an independent task, such as a backend fix and a UI change, on separate branches. This is the easiest pattern, but only works when the tasks genuinely do not touch the same files.

Step 4: Hand off with a written note

The weakest point is the handoff. Instead of pasting a long transcript, ask the first agent to write a short note the second agent can act on:

## Handoff: fix invitation retry
Goal: retrying an invitation must not invalidate a valid invite.
Constraint: invitations stay valid for 7 days.
Finding: each retry creates a new token (src/invites/retry.ts).
Tried: extending expiry (rejected: breaks the 7-day rule).
Next: reuse the existing token on retry and add a retry state.
Tests: npm test -- invites

Goal, constraints, finding, what was tried, the next step and how to verify it. That is usually all the next agent needs.

Step 5: Review before anything merges

Read the diff, run the tests yourself, and check the result against the original goal rather than against the agent’s summary of it. If the reviewing agent and the implementing agent disagree, that disagreement is worth your attention.

Step 6: Keep the lesson

When a fix teaches you something about the codebase, such as “reuse valid tokens when retrying invitation requests,” write it down where both agents will see it next time, for example in AGENTS.md. Keep these lessons short, scoped and reviewed, or the file turns into noise.

Common mistakes

• Two agents editing the same working tree at once.
• Handing off a full transcript instead of a focused note.
• Letting the agents’ instructions drift apart in two separate files.
• Merging because both agents agreed, without running the tests yourself.
• Saving every observation as a “lesson,” so the useful ones get lost.

Doing this without the manual work

Everything above works by hand, and it is worth trying that way first. COLLASTRA automates the coordination: it plans the task, runs Claude Code and Codex on your repository, carries the goal, files and findings across each handoff, shows you the diff to approve before it opens a pull request, and keeps reviewed lessons in OctaMem shared memory. Read what AI coding agent orchestration is or see how COLLASTRA works.