Using Git Worktrees for Parallel OpenAI Codex Sessions

Overview

Run multiple OpenAI Codex sessions in parallel on the same repository by using Git worktrees. This technique allows you to work on different features or experiments simultaneously without switching branches.

What You'll Learn

How to set up and use Git worktrees to run multiple independent OpenAI Codex sessions on the same codebase.

Prerequisites

• Git 2.5 or newer
• OpenAI Codex CLI installed
• A Git repository

Steps

Step 1: Create a New Worktree

From your main repository, create a new worktree for a specific branch or feature:

git worktree add ../myproject-feature-x feature-x

This creates a new directory ../myproject-feature-x with the feature-x branch checked out.

Step 2: Create Multiple Worktrees

Set up different worktrees for different tasks:

# For a bug fix
git worktree add ../myproject-bugfix bugfix-branch

# For an experiment
git worktree add ../myproject-experiment -b new-experiment

# For reviewing a PR
git worktree add ../myproject-pr-review pr-branch

Step 3: Run OpenAI Codex in Each Worktree

Open separate terminal windows and run OpenAI Codex in each worktree:

# Terminal 1
cd ../myproject-feature-x
codex

# Terminal 2
cd ../myproject-bugfix
codex

# Terminal 3
cd ../myproject-experiment
codex

Step 4: Work in Parallel

Each OpenAI Codex session operates independently:

• Different branches
• Different file states
• Different contexts
• No interference between sessions

Example Workflow

# Main repository
cd ~/projects/myapp

# Create worktrees for parallel work
git worktree add ../myapp-auth implement-auth
git worktree add ../myapp-ui update-ui
git worktree add ../myapp-tests add-tests

# Run OpenAI Codex in each
cd ../myapp-auth && codex   # Work on authentication
cd ../myapp-ui && codex      # Work on UI updates
cd ../myapp-tests && codex   # Work on test suite

Managing Worktrees

List All Worktrees

git worktree list

Remove a Worktree

# First, leave the worktree directory
cd ~/projects/myapp
git worktree remove ../myapp-feature-x

Prune Stale Worktrees

git worktree prune

Benefits

• True Parallelism: Run multiple OpenAI Codex sessions without context switching
• Isolation: Each session has its own working directory
• Speed: No need to stash/switch/pull between tasks
• Comparison: Easy to compare implementations across worktrees

Tips & Best Practices

• Name worktrees descriptively (e.g., myapp-auth, not just auth)
• Keep worktrees in a parallel directory structure
• Clean up worktrees when done to avoid clutter
• Use worktrees for long-running OpenAI Codex sessions
• Commit changes in each worktree before removing

Common Use Cases

1. Feature Development: Work on multiple features simultaneously
2. Bug Fixes: Fix bugs while continuing feature work
3. Experiments: Try different approaches without affecting main work
4. Code Reviews: Review PRs while working on other tasks
5. A/B Testing: Compare different implementations side-by-side

Troubleshooting

Issue: "fatal: 'feature-x' is already checked out" Solution: You can't have the same branch in multiple worktrees. Create a new branch or use a different existing branch.

Issue: Worktree directory already exists Solution: Choose a different directory name or remove the existing directory first.

References

• Git Worktree Documentation