Run Claude Code and Codex CLI in tmux Without File Conflicts

Running Claude Code and Codex CLI at the same time is easy: open two terminals and start both commands. The hard part begins five minutes later, when both agents edit the same file, one test run sees the other's half-finished changes, or nobody remembers which terminal owns which branch.

For Codex CLI alone, the shortest durable setup is one Git worktree per writing session and one tmux pane rooted in each worktree. Start Codex inside the pane, detach when you leave, and reattach to the same process later. Add Claude Code only when a second provider has a clear implementation or review role.

The reliable setup is not an elaborate agent hierarchy. It is a small operating rule: one writer per worktree, one explicit handoff point, and one terminal pane per agent. Git worktrees isolate files, tmux keeps the sessions visible and persistent, and MCP gives either agent access to the external tools it actually needs.

This guide builds that setup for one specific workflow: Claude Code implements a change, then Codex reviews the resulting commit from a separate pane. It also shows how to adapt the layout when both agents need to implement independent tasks. If you only need several Claude sessions, the existing parallel Claude Code worktree guide is the narrower route. This article is about coordinating different providers without turning a repository into shared mutable state.

Scope note: the tmux layout below is for the local Codex CLI. OpenAI also provides a Codex IDE extension and Codex cloud environments. Those are useful complementary surfaces, but they do not automatically share a local tmux pane or the same uncommitted checkout.

When the pair needs attention away from your desk, the Codex phone control guide compares OpenAI's native mobile Remote tab with a tmux-level mobile view for Codex CLI, Claude Code, OpenCode, and shell panes.

Before launching either agent, decide who is allowed to change which checkout. A tmux pane is only a process boundary; it is not a file-locking system. A separate Git worktree is the boundary that prevents one agent from reading another agent's half-finished edits.

Role	Checkout	Write policy	Handoff
Claude Code implementer	.worktrees/feature	May edit the feature files and run tests	Focused commit on agent/feature
Codex reviewer	Clean checkout or detached commit	Read-only; do not repair the author's branch	Findings tied to the reviewed commit
Second writer	.worktrees/tests	Owns a separately named task and file set	Independent branch to merge later
Human merge step	Primary checkout	Resolves semantic conflicts and accepts findings	Merge or rebase after both checks pass

For a review-only Codex session, the most important isolation is temporal: review a committed SHA, not a directory that is still changing. For two writing agents, the isolation must be both temporal and physical: use separate worktrees, give each prompt explicit ownership, and merge one branch at a time.

These tools solve different layers of the problem. Claude Code and Codex CLI do the reasoning and coding. Model Context Protocol (MCP) connects an agent to outside tools and data. tmux keeps terminal processes alive and arranges them into panes. Git worktrees give each writer an independent checkout and branch.

Layer	Tool	What it solves	What it does not solve
Agent	Claude Code or Codex CLI	Reads, edits, tests, and reviews code	Isolation from another writer
External tools	MCP	Access to GitHub, docs, issue trackers, browsers, and internal services	Agent coordination or file ownership
Terminal	tmux	Persistent sessions, panes, and readable pane scrollback	Filesystem isolation
Repository	Git worktrees	Separate working directories and branches backed by one repository	Task assignment or review policy

Both agents can consume MCP servers. Claude Code supports local, project, and user-scoped servers through claude mcp and .mcp.json; see the Claude Code MCP documentation. Codex CLI supports STDIO and Streamable HTTP servers through codex mcp and config.toml; see the Codex MCP documentation.

That common protocol does not mean the clients share approval decisions or conversation state. Codex CLI, its IDE extension, and the desktop app can share Codex MCP configuration, while Claude Code maintains its own client configuration. Register the same server with each client only when both agents need it, and give each role only the credentials it requires. Treat MCP as a shared interface, not as the manager of the two agents.

The safest default is an implementer-reviewer pair. One agent owns all writes. The other receives a stable commit and reports findings. This keeps the review independent and makes the handoff visible in Git.

Pattern	Claude Code	Codex CLI	Use when
Implement then review	Writes the feature branch	Reviews a committed SHA	One feature needs a second opinion
Two independent tasks	Writes worktree A	Writes worktree B	Tasks own different modules or deliverables
Competing approaches	Implements option A	Implements option B	You will compare and keep one result

Avoid assigning both agents "fix the authentication code" in the same checkout. tmux will show two panes, but both processes still see and modify the same files. Even when the edits do not produce a Git conflict, one agent can validate against an intermediate state created by the other. The result may pass once and fail after either agent finishes.

Write ownership into each prompt. Give the implementer the exact branch or worktree it owns. Tell the reviewer it is read-only and should return findings ordered by severity. If both agents are writers, define separate outcomes such as "API implementation" and "integration tests" rather than asking both to solve the whole feature.

Start from a clean primary checkout. Keep agent worktrees under a repository-local .worktrees/ directory so the project and its temporary checkouts stay together. Add .worktrees/ to the repository's .gitignore once, then create a named branch and worktree for each writing agent:

cd ~/code/myapp
git fetch origin
mkdir -p .worktrees

git worktree add .worktrees/claude-auth -b agent/claude-auth origin/main
git worktree add .worktrees/codex-tests -b agent/codex-tests origin/main

The two directories share Git objects, but their checked-out files, indexes, and branches are independent. Claude can edit .worktrees/claude-auth while Codex edits .worktrees/codex-tests without either process seeing the other's uncommitted files. Keeping the paths inside the repository also gives scripts, ClawTab jobs, and human reviewers one predictable place to find every active checkout.

For the implementer-reviewer pattern, only the implementer needs a writing worktree. A Codex review can target the implementer's commit SHA from any worktree connected to the same repository:

# In the Claude worktree after tests pass
git add -A
git commit -m "Implement authentication refresh"
git rev-parse HEAD

# In the Codex pane, review that immutable handoff
codex review --commit <commit-sha>

codex review --commit is preferable to pointing both agents at uncommitted files. The reviewer sees a stable diff, the author can reproduce every finding, and the review cannot silently change underneath either session. After review, send the findings back to the writing agent and create a second commit. Keep one writer until that branch is ready to merge.

Claude Code also has native worktree support through claude --worktree, documented in Run parallel sessions with worktrees. Manual git worktree add is useful here because it gives both providers the same explicit directory convention.

Create a tmux session with one pane rooted in each worktree. The working directory on the pane matters more than the visual layout:

tmux new-session -d -s ai-pair -c ~/code/myapp/.worktrees/claude-auth
tmux send-keys -t ai-pair:0.0 'claude' Enter

tmux split-window -h -t ai-pair:0 -c ~/code/myapp/.worktrees/codex-tests
tmux send-keys -t ai-pair:0.1 'codex' Enter

tmux select-layout -t ai-pair:0 even-horizontal
tmux attach -t ai-pair

Now detaching with Ctrl-b d leaves both agents running. Reattach with tmux attach -t ai-pair. A terminal disconnect no longer destroys the work, and the two pane paths make ownership inspectable.

Use a short pane checklist before prompting either agent:

• Run pwd and git branch --show-current in each pane.
• Confirm the branches differ before enabling any automatic approvals.
• Put the owned task and forbidden paths in each initial prompt.
• Keep a shell or reviewer pane read-only unless it has its own worktree.

tmux is the persistence and layout layer. It does not know whether an agent is waiting for approval, finished, or stuck. For a larger workspace, an agent manager built on tmux can add that operational state without replacing the terminal sessions.

You do not need a second provider to benefit from this layout. For one Codex task, create a worktree, start a detached tmux session in that directory, launch Codex, and attach:

git worktree add .worktrees/codex-auth -b agent/codex-auth origin/main
tmux new-session -d -s codex-auth -c "$PWD/.worktrees/codex-auth"
tmux send-keys -t codex-auth:0.0 -l 'codex'
tmux send-keys -t codex-auth:0.0 Enter && tmux attach -t codex-auth

Detach with Ctrl-b d. The Codex process continues in the tmux server. Reattach with tmux attach -t codex-auth. Before prompting Codex, run pwd and git branch --show-current so the worktree boundary is visible in the transcript.

For a second Codex writer, repeat the pattern with a different branch, directory, and tmux session name. Do not split a second writer into the same checkout just because the panes look separate. tmux isolates terminals; Git worktrees isolate files.

Manual tmux is enough when you can remember a few session names and inspect each pane directly. A manager becomes useful when the number of panes exceeds what you can scan, or when agents need attention while you are away.

Approach	What it automates	Use it when
Plain tmux + Git worktrees	Durable terminals and file isolation; you own naming, status, and cleanup	You run a few sessions and want the smallest dependency set
dmux or workmux	Worktree creation, terminal layout, agent launch, status, and merge cleanup	You want a terminal-first task lifecycle
webmux, AgentDock, or Agent of Empires	Browser or TUI dashboards, worktree controls, status, and varying mobile paths	You want a manager-owned workspace and remote web surface
ClawTab	Discovery of existing panes, working/asking/idle state, native desktop splits, mobile answers, restore commands, and schedules	You want the same local pane available through tmux, desktop, phone, CLI, and Telegram

The maintained AI coding agent dashboard comparison checks the current attachment model, provider coverage, worktree lifecycle, notifications, mobile control, and recovery behavior for all six products. The key choice is whether the manager should create every task or attach to sessions you already run.

Codex has several surfaces, and choosing the wrong one can make a tmux tutorial feel confusing. The CLI keeps the coding loop in a terminal and can inspect a local diff before you commit. The IDE extension keeps Codex beside open files and selections. Codex cloud runs coding tasks in a managed environment and returns a result for you to review or apply.

Codex surface	Where the work happens	Best fit	How it relates to this guide
Codex CLI	Your terminal and local checkout	Local edits, tests, scripting, and commit-based review	Use a tmux pane and a worktree
Codex IDE extension	Your editor	Focused edits with open-file and selection context	Use it as an interactive editor workflow, not as a second tmux writer
Codex cloud	A configured cloud environment	Longer delegated tasks while your laptop is closed	Review and apply its result through the Codex workflow before merging

If your goal is Claude Code and Codex running side by side on the same Mac, choose the CLI row. If your goal is to delegate work away from the machine, choose Codex cloud and keep the local worktree available for review. The broader AI coding agent and manager comparison covers how this choice differs from Cursor, Claude Code, OpenCode, and ClawTab.

tmux panes can also act as a lightweight context channel between agents. An agent with access to the same tmux server can discover the other panes and read their recent terminal output without interrupting them:

# Find pane ids, working directories, and foreground commands
tmux list-panes -a -F '#{pane_id} #{pane_current_path} #{pane_current_command}'

# Read the latest 200 lines from another agent's pane
tmux capture-pane -p -t %42 -S -200

Give each agent the stable pane id it may inspect and a narrow instruction such as:

When you need implementation context, read pane %42 with tmux capture-pane.
Use its recent logs and test output as supporting context only.
Do not use tmux send-keys or otherwise control that pane.

This lets Codex retrieve Claude's latest test failure, file list, or progress summary before reviewing, and lets Claude inspect a review pane for new findings. Refresh capture-pane when needed rather than copying entire conversations into prompts.

Pane output is not the other agent's complete model context. Scrollback can be truncated, stale, or include sensitive command output. Treat it like a shared log: grant read access deliberately, avoid printing secrets, verify important conclusions against Git and test results, and keep tmux send-keys disabled unless one agent is explicitly authorized to control another.

If both agents need the same remote MCP server, register its endpoint in both clients:

claude mcp add --transport http team-tools --scope project https://mcp.example.com/mcp
codex mcp add team-tools --url https://mcp.example.com/mcp

The endpoint is shared; the client configuration is not. Claude's project scope writes a team-shareable .mcp.json. Codex stores MCP settings in its own config.toml, with project-scoped configuration available under .codex/config.toml for trusted repositories. Each client also has its own tool approvals and OAuth state.

Do not commit access tokens into either file. Reference environment variables, and give each role only the credentials it needs. A reviewer usually needs repository and issue access but not production database writes. An implementation agent may need a test environment but not deployment permissions. ClawTab's per-job secrets keep those environments separate even when both panes belong to the same tmux window.

There is a more tightly coupled option: Codex can run as an MCP server, and Claude Code can consume STDIO MCP servers. That makes agent-inside-agent workflows possible, but it is not the default recommended here. Independent panes have clearer logs, separate stop controls, simpler permissions, and an explicit Git handoff. Nest the agents only when the outer agent genuinely needs to call Codex as a tool rather than when you merely want a second review.

A good two-agent loop has four states, each represented by something you can inspect:

1. Assigned: one prompt names the owner, worktree, acceptance criteria, and forbidden paths.
2. Implemented: the writer runs tests and creates a focused commit.
3. Reviewed: the second agent reviews the commit SHA and returns findings without editing the branch.
4. Resolved: the original writer addresses accepted findings in a new commit, then the human merges.

This loop is deliberately asymmetric. Two models can contribute, but only one process owns the branch at any moment. If a finding is large enough to become a separate task, create another branch and worktree instead of letting the reviewer begin editing the author's checkout.

For two independent writers, merge or rebase one completed branch at a time. After the first branch lands, update the second worktree against the new base and rerun its tests. Worktrees prevent live file collisions; they do not remove normal semantic merge conflicts between two valid branches.

The same discipline scales beyond two agents. The agent swarm guide covers larger parallel runs, while the session restore guide explains how to reconnect the exact Claude Code and Codex conversations after tmux or the machine restarts.

Worktree isolation prevents live file collisions, but it does not prove that the branches are compatible. Before merging a Claude Code or Codex branch, use a short, repeatable gate:

Check	What it catches
git status --short	Uncommitted files that would make the handoff ambiguous
git diff --check	Whitespace errors and malformed patch boundaries
Fresh-worktree test run	Tests that only pass because another pane left generated files or services running
Review findings by path and severity	Vague feedback that cannot be reproduced by the writing agent
Rebase the second writer after the first merge	Semantic conflicts hidden by two otherwise clean branches

Keep the commit SHA, test command, and reviewer findings together in the handoff note. That small record is more reliable than copying the latest terminal output between panes, especially after a tmux session is detached or restored.

ClawTab turns the manual setup into a visible workspace without changing the underlying safety model. Create one Claude Code job and one Codex job, assign each job its worktree as the working directory, and place both in the same tmux window. The panes remain ordinary terminal sessions, so Git and provider-native resume commands still work.

The useful additions are operational:

• Provider and pane visibility. Claude Code and Codex sessions appear side by side with their current state.
• Per-pane approval policy. Keep the reviewer conservative while allowing a tightly scoped implementation job to proceed.
• Per-job secrets. Inject different MCP credentials and environment variables into each role.
• Session recovery. Map tmux panes back to the correct Claude or Codex conversation instead of reopening fresh sessions.
• Remote monitoring. Check output and answer a blocked prompt without taking over the writer's terminal.

The point is not to make Claude Code and Codex communicate continuously. It is to make ownership, state, and handoffs obvious enough that a human can safely use both. Agents can inspect approved pane logs when they need fresh context, while commits remain the authoritative handoff. Start with one writer and one reviewer. Add a second writing worktree only when the tasks are genuinely independent.