OpenAI Codex with Git Worktree

How Codex Uses Worktrees

Codex operates by creating a sandbox for each coding task. When you give Codex a task, it spins up an isolated environment where the agent can read, modify, and test code without affecting your main working directory. Git worktrees are the mechanism that makes this isolation possible.

Each Codex agent session creates a new worktree from your repository, checks out a fresh branch, and works entirely within that directory. The agent can run commands, install dependencies, run tests, and make commits, all without touching your main branch or any other agent's workspace.

When the agent finishes, the result is a branch with clean commits that you can review and merge using your normal workflow. If the agent's work is not useful, you simply delete the branch and remove the worktree.

Setting Up Git Worktree for Codex

To prepare your repository for Codex worktree sessions, ensure you have a clean git repository with all changes committed:

# Make sure your repo is clean
git status

# Create worktrees for Codex agents
git worktree add ../codex-task-1 -b codex/task-1
git worktree add ../codex-task-2 -b codex/task-2
git worktree add ../codex-task-3 -b codex/task-3

# Verify
git worktree list

Using a codex/ branch prefix makes it easy to identify which branches were created for Codex sessions when you list them later. For more on the add command, see our git worktree add tutorial.

Docker Compose Configuration

Codex agents often run inside Docker containers for additional isolation. When using Docker Compose with git worktrees, you need to mount the worktree directories and ensure the containers can access the shared git object store.

# docker-compose.yml for Codex with git worktrees
version: "3.8"

services:
  codex-agent-1:
    image: codex-agent:latest
    volumes:
      # Mount the worktree directory
      - ../codex-task-1:/workspace
      # Mount the main .git directory (worktrees need access to it)
      - ./.git:/workspace/.git-main:ro
    working_dir: /workspace
    environment:
      - GIT_DIR=/workspace/.git
      - TASK=implement-auth-api

  codex-agent-2:
    image: codex-agent:latest
    volumes:
      - ../codex-task-2:/workspace
      - ./.git:/workspace/.git-main:ro
    working_dir: /workspace
    environment:
      - GIT_DIR=/workspace/.git
      - TASK=fix-pagination-bug

  codex-agent-3:
    image: codex-agent:latest
    volumes:
      - ../codex-task-3:/workspace
      - ./.git:/workspace/.git-main:ro
    working_dir: /workspace
    environment:
      - GIT_DIR=/workspace/.git
      - TASK=add-unit-tests

The critical detail is the .git mount. Git worktrees use a small .gitfile in each worktree directory that points back to the main repository's .git directory. Inside Docker, this reference needs to be valid, so you mount the main .git directory into the container as well.

Start all agents simultaneously with:

# Launch all Codex agents in parallel
docker compose up -d

# Monitor agent progress
docker compose logs -f

# Stop all agents
docker compose down

Codex Worktree Skills

Codex agents have built-in capabilities for working with git inside their sandboxed environments. These include:

• Branch management: The agent can create, switch, and manage branches within its worktree without affecting other worktrees.
• Commit creation: Each agent creates commits on its own branch, building a clean history of its changes.
• Test execution: Agents can run your test suite inside the worktree to validate their changes before marking the task as complete.
• Dependency installation: Agents install dependencies specific to their worktree without polluting other worktrees or the main checkout.

These skills work naturally with worktrees because each agent's file operations are scoped to its own directory.

Running Multiple Codex Agents

The typical workflow for parallel Codex development involves three steps: create worktrees, run agents, and merge results.

#!/bin/bash
# codex-parallel.sh - Run multiple Codex agents in parallel

REPO_DIR=$(pwd)
TASKS=("implement-search" "fix-caching" "add-logging")

# Step 1: Create a worktree for each task
for task in "${TASKS[@]}"; do
  git worktree add "../codex-$task" -b "codex/$task"
  echo "Created worktree for $task"
done

# Step 2: Launch a Codex agent in each worktree
for task in "${TASKS[@]}"; do
  (cd "../codex-$task" && codex run --task "$task") &
done

# Wait for all agents to finish
wait
echo "All agents complete"

# Step 3: List results
git worktree list
for task in "${TASKS[@]}"; do
  echo "\n--- Branch codex/$task ---"
  git log --oneline "codex/$task" -5
done

After reviewing each agent's changes, merge the branches you want to keep and clean up the rest. For detailed merge strategies, see our parallel agents guide.

Best Practices