Skip to content
BSWEN
Blog

How to Run Multiple Codex CLI Sessions in Parallel with Git Worktrees

Cowrie
Cowrie
Dev @ Bswen

I was stuck waiting for Codex to finish a task. My quota was at 1%. I couldn’t start another feature because the session was blocked. This wasted hours every week.

Then I found a better way: run multiple Codex sessions in parallel using git worktrees.

The Problem with Single-Session Workflow

When you use Codex CLI, you typically run one session at a time. This creates a bottleneck:

  • You wait for one task to complete before starting another
  • If Codex hits quota limits, you’re stuck
  • You can’t parallelize work across multiple features

I tried opening multiple terminal tabs. But Codex sessions share state and conflict with each other. The files get mixed up. Errors happen.

The Solution: Git Worktrees + agent-orchestrator

Git worktrees let you check out multiple branches into separate directories. Each directory is independent. This means you can run one Codex session per worktree without conflicts.

The key tool is agent-orchestrator. It manages parallel Codex sessions across worktrees automatically.

Step 1: Create Git Worktrees

First, create a worktree for each task you want to work on:

Create worktrees for parallel work
git worktree add ../feature-auth -b feature/auth-system
git worktree add ../fix-bug -b fix/memory-leak

Each worktree is a separate directory. You can switch between them without git stash or losing work.

Step 2: Run agent-orchestrator

Now run agent-orchestrator to start parallel Codex sessions:

Run parallel Codex sessions
agent-orchestrator run \
  --worktrees ../feature-auth ../fix-bug \
  --auto-handle-ci

The orchestrator does the following:

  • Spawns one Codex agent per worktree
  • Monitors CI failures and auto-triages them
  • Keeps sessions isolated and conflict-free

Why This Matters

Parallel work compounds your output. Instead of doing three tasks sequentially, you do them simultaneously.

Consider the difference:

  • Sequential: Task A (2h) → wait → Task B (2h) → wait → Task C (2h) = 6+ hours
  • Parallel: Task A, B, C all start = ~2 hours total

When Codex 5.5 grinds at 1% quota, parallelizing across worktrees still compounds productivity. You’re not waiting on one bottleneck.

Common Mistakes

Not Using Worktrees

Some developers try to run multiple Codex sessions in the same directory. This fails because:

  • Sessions overwrite each other’s files
  • Git state gets corrupted
  • Context and memory clash between agents

Always use worktrees for isolation.

Running a Single Session

If you only have one task, a single session is fine. But most developers have multiple pending tasks. Running one at a time wastes your potential output.

Quick Start Checklist

  1. Install agent-orchestrator from GitHub
  2. Create one worktree per task
  3. Run orchestrator with all worktree paths
  4. Monitor progress and review results

This approach turns Codex from a single-threaded tool into a parallel workforce. Your productivity scales with the number of worktrees you can manage.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!

Comments

Tags: