How to run Claude Code and Codex in parallel
Use Claude Code and Codex together with isolated worktrees, bounded responsibilities, independent runtimes, and one review queue.
Maintained by the Matrix OS team. Product instructions are updated with the supported workflow.
You can run Claude Code and Codex in parallel on the same project when each agent has a separate Git worktree, branch, terminal, port range, and development database. Give them independent deliverables and merge their work through one human-controlled review queue.
What work should Claude Code and Codex do in parallel?
A useful split produces artifacts that can be evaluated independently:
- Claude Code fixes a specific backend issue while Codex adds frontend tests.
- Codex implements a bounded change while Claude Code reviews the resulting branch.
- Claude Code investigates a failure while Codex reproduces it in a separate environment.
- Each agent attempts the same bug on separate branches for comparison. A human chooses one approach.
Avoid assigning both agents to “work on the feature.” That usually produces two partial implementations, two different assumptions about the API, and a merge conflict in the files that matter most.
How do you isolate both agents in the same repository?
git fetch origin
git worktree add ../repo-claude -b agent/claude origin/main
git worktree add ../repo-codex -b agent/codex origin/mainOn the remote computer, start each tool in a separate Terminal tab from its own directory:
cd ~/projects/repo-claude
claudeIn the second Terminal tab:
cd ~/projects/repo-codex
codexDo not let two writing agents share a checkout even if they promise to edit different files. Generated files, formatters, package locks, Git state, and test artifacts are shared surfaces.
How do you keep both agents running remotely?
If you prefer the CLI, open two local terminals and connect them to the same Matrix computer. The worktrees above must already exist under ~/projects on that computer.
In the first local terminal:
matrix run -it --project main -C projects/repo-claude -- claudeIn the second:
matrix run -it --project main -C projects/repo-codex -- codexEach interactive run creates a new remote tab. Detach with Ctrl-\ Ctrl-\, then list and reconnect to the existing tab instead of starting another run:
matrix shell ls
matrix shell connect --project main --tab YOUR_TAB_IDReplace YOUR_TAB_ID with the real ID for the desired agent. Disconnecting your laptop leaves remote processes running; host restarts, agent exits, approval prompts, and provider limits still apply. See the cloud migration guide to verify the remote setup before running multiple agents.
Why are separate worktrees not enough?
File isolation is not enough. Assign unique values such as:
# Claude worktree
PORT=3101
DATABASE_URL=postgresql://localhost/repo_claude
# Codex worktree
PORT=3102
DATABASE_URL=postgresql://localhost/repo_codexUse disposable data for migrations and destructive tests. Never give either agent production credentials merely because the remote computer is isolated from your laptop.
How do you review and merge two agent branches?
Review the first completed branch, rerun its tests, and merge it. Then rebase the second branch onto the updated target and run tests again. Parallel agents create work concurrently. Integration is still an ordered engineering decision.
Track useful throughput rather than agent count:
- reviewable tasks completed,
- tests passing after integration,
- conflicts per branch,
- human review time,
- rework caused by incorrect assumptions.
Common questions about using Claude Code and Codex together
Is it better to have Claude review Codex or vice versa?
Either can provide a useful second pass, but model review is not a substitute for tests and accountable human review. Keep the reviewer agent read-only until you deliberately request a follow-up patch.
Can both agents use the same database?
They can for read-only work. Concurrent tests, fixtures, migrations, and writes should use separate databases or schemas.
Which agent should get which task?
Route by demonstrated performance in your repository, not general reputation. Track completion quality, review time, test success, and rework for each task class.
