1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
| title: "Codex CLI Lacks Worktrees (Here's How to Set Them Up Yourself)"
date: 2026-03-11T23:45:00+01:00
draft: false
slug: "codex-cli-worktrees-manual-parallelism"
slug_en: "codex-cli-worktrees-manual-parallelism"
description: "Codex CLI doesn’t support --worktree or --tmux. But with manual Git worktrees and a few tricks, you can achieve real parallelism. A practical guide with the bugs you’ll encounter."
tags: ["codex", "openai", "git", "worktrees", "agents", "productivity"]
categories: ["tools"]
translation:
hash: ""
last_translated: ""
notes: |
- "montártelo": colloquial for "to set it up yourself" / "to rig it up". Not sexual.
- "te la pegas": "you crash" / "you hit a wall". Colloquial for failing/getting burned.
- "ñapa": "quick hack/bodge". Not derogatory, somewhat affectionate.
- "currar": colloquial for "to work". Very common in Spain.
- "ir tirando": "to get by" / "to make do". Casual.
- "el ajo": "garlic" — used in "meterse en el ajo" meaning "to get into the thick of it".
- "tela marinera": expression meaning "that's quite something" / "no small feat". No textile connotation.
social:
publish: true
scheduled_date: 2026-03-14
platforms: ["twitter", "linkedin"]
excerpt: "Codex CLI doesn't support --worktree or --tmux for parallel operations. But with manual worktrees and attention to shared-session bugs, you can create truly parallel workflows. Practical guide."
wordpress:
publish: true
categories: [1]
tags: ["codex", "openai", "git", "worktrees", "productivity"]
video:
generate: false
style: "educational"
---
If you’ve read my [post about worktrees in Claude Code](/en/claude-code-worktrees-parallelism-agents/), you know the key to parallel workflows is a simple flag: `--worktree`. Run it, and you get an agent working in its own isolated repo copy. Launch three, and you’ve got three agents working in parallel without clashing. Magic.
Now you open Codex CLI, look for an equivalent flag… and it doesn’t exist.
There’s no `--worktree`. No `--tmux`. No `isolation: worktree` for custom agents. [Issue #12862](https://github.com/openai/codex/issues/12862) has been open on GitHub asking for exactly this, with community members proposing their own implementations in forks, but nothing has been merged. Native parallelism for Codex CLI doesn’t exist — not yet.
Does that mean you can’t work in parallel with Codex? No. It just means you’ve got to do it yourself. And by “do it yourself,” I mean three git commands and a few precautions to avoid crashing and burning.
## The Plan: Manual Worktrees + One Codex Per Directory
The concept is the same as with Claude Code, but without automation. You create the worktrees, you launch the agents, and you clean up afterward. It’s handcrafted, but it works.
```bash
# From your main repo
cd ~/code/my-project
# Create one worktree per task
git worktree add ../my-project-feat-auth -b feature/auth
git worktree add ../my-project-fix-tests -b fix/broken-tests
git worktree add ../my-project-refactor -b chore/refactor-db
|
Now you’ve got four directories: the main repo and three worktrees. Each one has its own branch, its own staging area, and its own independent HEAD. They share the Git database (.git/), but otherwise, they are isolated copies.
The next step is to launch a Codex instance in each:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
| # Terminal 1
cd ../my-project-feat-auth
codex --approval-mode never --sandbox workspace-write \
"Implement JWT authentication middleware. Write tests."
# Terminal 2
cd ../my-project-fix-tests
codex --approval-mode never --sandbox workspace-write \
"Run the test suite, fix all failing tests, repeat until green."
# Terminal 3
cd ../my-project-refactor
codex --approval-mode never --sandbox workspace-write \
"Refactor the database module to use connection pooling."
|
Three agents, three tasks, zero interference. Each Codex instance only sees its own worktree and operates on its own branch.
The Bug That’s Going to Bite You: Shared Sessions#
Here’s the part you won’t find in any official tutorial. There’s a known bug (#11435) in Codex CLI: all instances share the session directory ~/.codex/. If you launch three Codex instances in parallel, they can load each other’s contexts, corrupting execution.
To put it plainly: the agent fixing tests might suddenly think it’s working on authentication because it read the other instance’s session.
The fix? Force a separate session directory for each instance:
1
2
3
4
5
6
7
8
| # Terminal 1
CODEX_HOME=~/.codex-session-1 codex --approval-mode never --sandbox workspace-write "..."
# Terminal 2
CODEX_HOME=~/.codex-session-2 codex --approval-mode never --sandbox workspace-write "..."
# Terminal 3
CODEX_HOME=~/.codex-session-3 codex --approval-mode never --sandbox workspace-write "..."
|
If CODEX_HOME doesn’t work in your version (the variable name has changed between releases), the nuclear alternative is to copy a unique config.toml file into each worktree:
1
2
3
| # In each worktree
mkdir .codex
cp ~/.codex/config.toml .codex/config.toml
|
It’s not elegant. It’s a quick hack. But it works, and it’s the only solution until they merge issue #12862.
Automating It: A Wrapper Script#
If you’re doing this often, a script will save you from making mistakes:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
| #!/usr/bin/env bash
# codex-worktree.sh — Launch Codex in an isolated worktree
set -euo pipefail
BRANCH="$1"
PROMPT="$2"
REPO_NAME=$(basename "$(pwd)")
WORKTREE_DIR="../${REPO_NAME}-${BRANCH//\//-}"
SESSION_DIR="$HOME/.codex-session-$$"
# Create worktree
git worktree add "$WORKTREE_DIR" -b "$BRANCH" 2>/dev/null || \
git worktree add "$WORKTREE_DIR" "$BRANCH"
echo "→ Worktree: $WORKTREE_DIR"
echo "→ Session: $SESSION_DIR"
echo "→ Branch: $BRANCH"
# Launch Codex with isolated session
cd "$WORKTREE_DIR"
CODEX_HOME="$SESSION_DIR" codex \
--approval-mode never \
--sandbox workspace-write \
"$PROMPT"
# Clean up session (leave worktree for review)
rm -rf "$SESSION_DIR"
echo "✓ Session cleaned. Worktree at $WORKTREE_DIR ready for review."
|
Usage:
1
2
| ./codex-worktree.sh feature/auth "Implement JWT auth middleware with tests"
./codex-worktree.sh fix/tests "Fix all failing tests"
|
Each invocation creates a worktree, sets up an isolated session, launches Codex, and cleans up the session after execution. The worktree remains for you to review the results before merging.
With tmux: Visual Parallelism#
If you want to watch all three agents working simultaneously, tmux is your friend:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
| # Create a tmux session with three panes
tmux new-session -d -s codex-parallel
# Pane 1: auth
tmux send-keys -t codex-parallel \
"cd ../my-project-feat-auth && codex --approval-mode never --sandbox workspace-write 'Implement auth'" Enter
# Pane 2: tests
tmux split-window -h -t codex-parallel
tmux send-keys -t codex-parallel \
"cd ../my-project-fix-tests && codex --approval-mode never --sandbox workspace-write 'Fix tests'" Enter
# Pane 3: refactor
tmux split-window -v -t codex-parallel
tmux send-keys -t codex-parallel \
"cd ../my-project-refactor && codex --approval-mode never --sandbox workspace-write 'Refactor DB'" Enter
# Attach to the session
tmux attach -t codex-parallel
|
Three panes, three agents, one view. It’s not claude --worktree --tmux, but visually it works just the same.
If manually setting all of this up feels like too much, there are community-built tools that can handle it for you:
parallel-code: runs Claude Code, Codex, and Gemini CLI in isolated worktrees automatically. Give it a task and an agent, and it handles creating the worktree, launching the process, and managing the session.
ccmanager: a session manager for multiple agents with worktree isolation. More feature-rich, supports multiple agent CLIs.
Both are community solutions, not official, but they fill the gap OpenAI hasn’t addressed yet.
What Codex App Has (And the CLI Doesn’t)#
To clarify: the Codex desktop app (released March 2026) does have native worktrees. When you create a thread, you can choose “Worktree” mode, and automations run in dedicated worktrees in the background.
But the app requires the desktop GUI to be running. If you’re working on a server, in a CI container, or simply prefer the terminal, the app doesn’t help. And the CLI, which is what you’d use in those contexts, lacks this feature.
It’s like if Git had worktrees in the GUI but not in the command line. Absurd, yet here we are.
The Honest Comparison#
| Feature | Claude Code | Codex CLI | Codex CLI + Manual Worktrees |
|---|
| Create worktree | --worktree (1 flag) | Not supported | git worktree add (manual) |
| Parallel sessions | --tmux (1 flag) | Bug #11435 | Manual tmux + isolated sessions |
| Isolated agents | isolation: worktree | Not supported | Wrapper script |
| Automatic cleanup | Yes | N/A | Manual (git worktree remove) |
| Merge back to main | Automatic | N/A | Standard git merge |
Claude Code has made worktrees completely invisible — just an implementation detail you don’t even think about. With Codex CLI, worktrees are plumbing you have to install yourself.
Does it work? Yes. Is it the same? No. The difference between native automation and doing it manually is like driving an automatic car versus cranking a hand-crank. Both get you where you’re going, but one steals the joy and leaves you sore.
Until Issue #12862 Gets Fixed#
The good news is that people are working on this. The issue has patches in forks, votes, and momentum. It’s only a matter of time.
For now, manual worktrees get the job done. They’re not pretty, and they’re not automated, but they let you achieve real parallelism with Codex CLI today. Three git commands, a bit of tmux, and care with shared-session bugs. That’s all it takes.
And if you’re wondering why Claude Code has solved this for months while Codex still hasn’t — well, sometimes being the second mover lets you copy what works. But you have to copy it, and so far, they haven’t.