The tasks were small. The backlog was not. This is the worst possible combo for a normal workflow because the fixed overhead dominates: branch setup, dependency sync, commits, reviewable diffs, and PR management. Doing it serially feels safe, but it is slow in a way that doesn’t show up in estimates.

So I tried the obvious cheat: run multiple AI agents in parallel.

It worked, but only after I tripped over three problems that are easy to reproduce if you try this without thinking through git state, shells, and sandbox boundaries.

What the system looked like (so you don’t think this is a demo problem)

I ended up writing a small orchestration script with three phases:

1. Create (or reuse) one worktree per task.
2. Install dependencies in parallel.
3. Run codex exec in batched parallel, then push branches and open draft PRs.

The key detail is that batching wasn’t “run everything at once”. It was “parallel within a batch, sequential across batches”, grouped by expected file overlap.

Here is the redacted shape of the script (this is not pseudocode; it’s a sanitized skeleton of what I ran):

 1#!/usr/bin/env zsh
 2set -euo pipefail
 3
 4WORKTREE_DIR=".worktrees"
 5BASE_BRANCH="<base-branch>"
 6LOG_DIR="${WORKTREE_DIR}/_logs"
 7
 8mkdir -p "${WORKTREE_DIR}" "${LOG_DIR}"
 9
10# Phase 1: worktrees + deps (parallel installs)
11hdr "Phase 1: Setting up worktrees"
12git worktree add -b "<feature-branch>" "${WORKTREE_DIR}/<lane>" "${BASE_BRANCH}"
13(cd "${WORKTREE_DIR}/<lane>/frontend" && bun install --frozen-lockfile) &
14(cd "${WORKTREE_DIR}/<lane>/backend"  && uv sync) &
15wait
16
17# Phase 2: batched parallel codex exec (one log per lane)
18hdr "Phase 2: Running Codex"
19codex exec --dangerously-bypass-approvals-and-sandbox -C "${WORKTREE_DIR}/<lane>" -m "${CODEX_MODEL}" "<prompt>" > "${LOG_DIR}/<lane>.log" 2>&1 &
20wait
21
22# Phase 3: push + PRs
23hdr "Phase 3: PRs to ${BASE_BRANCH}"
24git -C "${WORKTREE_DIR}/<lane>" push -u origin "<feature-branch>"
25gh pr create --base "${BASE_BRANCH}" --head "<feature-branch>" --draft --body "<templated body>"

Notice what this gives you immediately: one directory per lane, one log file per lane, and a clean boundary between “make changes” and “publish changes”.

Now for the parts that went wrong.

Failure #1: The shell lied about what “Bash” means

The first failure happened before any parallelism even started. The orchestration was written with associative arrays, and the system shell rejected it with:

1declare: -A: invalid option

This is the kind of bug that looks embarrassing until you realize it is inevitable. macOS ships an older Bash; other environments may default to sh; CI runners may use different interpreters. If your control-plane script can’t build the lane-to-branch mapping reliably, your entire run becomes a dice roll.

The fix was not “make it work on my machine”. The fix was pinning the interpreter and failing fast (set -euo pipefail). Once the script ran under the interpreter it was written for, this class of failure disappeared.

Failure #2: The sandbox was fine until it touched .git

The second failure was more instructive: everything looked successful until commit/push time, and then git failed when trying to write worktree metadata:

1fatal: Unable to create '.git/worktrees/<lane>/index.lock': Operation not permitted

The important mental model is: “can edit files” is not equivalent to “can finish delivery”. Git history mutation needs to create locks and update metadata under .git/. Sandboxed agents often allow workspace file edits while denying .git writes by design.

The fix is to treat permissions as architecture. In my runbook now, implementation and version-control mutation are distinct phases. I keep guardrails on while generating and editing code, and only elevate privileges for commit, rebase, push, and PR creation. That sounds procedural, but it is the difference between parallelism and chaos.

Failure #3: The PR diff was computed against the wrong reality

The third failure was the “ghost diff” class: the PR contained changes that “weren’t part of the task” even though the worktree looked clean locally. This is not a GitHub bug. It is a merge-base bug.

PR diff is computed from:

1merge_base(feature, base) .. feature

If your base ref is stale when the feature branch is compared, merge_base resolves behind your intended base, and commits that should be “already in base” appear as if they were introduced by the feature.

The only reliable approach is to verify ancestry before review and rebase if needed:

1git merge-base --is-ancestor origin/<base-branch> HEAD || echo REBASE_REQUIRED
2git diff --name-only origin/<base-branch>...HEAD

This takes seconds and saves you from burning reviewer attention on diff noise.

What changed once I actually read the Codex CLI docs

My first attempt treated Codex like a generic shell command that prints code. The docs made the control surface explicit, and that changed how I designed the run.

Approval and sandbox mode became part of the plan instead of an afterthought. Configuration precedence became something I could reason about when a lane behaved differently. Non-interactive codex exec became the default because it is scriptable and produces logs you can archive. And built-in review flows (like /review) became a lane-local quality gate before humans ever see the PR.

I also stopped mixing two different kinds of parallelism. Worktrees are for isolating tasks across lanes. Multi-agent mode is for decomposing one task inside a lane. When you treat them as separate tools, your system stays debuggable.

The boring checklist

At this point the process is intentionally boring, which is exactly what you want near a deadline. My checklist is short:

• If the lane can’t commit/push, it doesn’t “count” as done. Fix the permission boundary first.
• If the PR diff scope isn’t what you expect, stop and fix ancestry before asking for review.
• If a lane doesn’t have a log file, assume it didn’t run deterministically.

Appendix: Redacted Script Skeleton

Below is a condensed, anonymized skeleton of the script I used. It preserves the mechanics (worktrees, batching, logs, PR creation) but removes identity details.

 1#!/usr/bin/env zsh
 2set -euo pipefail
 3
 4BASE_BRANCH="<base-branch>"
 5WORKTREE_DIR=".worktrees"
 6LOG_DIR="${WORKTREE_DIR}/_logs"
 7
 8mkdir -p "${WORKTREE_DIR}" "${LOG_DIR}"
 9
10typeset -A TASK_BRANCH TASK_TITLE TASK_PLAN TASK_LABEL
11TASK_BRANCH[001]="feature/lane-001"
12TASK_TITLE[001]="Lane 001: <title>"
13TASK_PLAN[001]="docs/plans/<plan>.md"
14TASK_LABEL[001]="<label>"
15
16BATCH_1=(001 002)
17BATCH_2=(003)
18
19setup_lane() {
20  local id="$1"
21  local branch="${TASK_BRANCH[$id]}"
22  local worktree="${WORKTREE_DIR}/lane-${id}"
23
24  if [[ -d "${worktree}" ]]; then
25    echo "Reusing ${worktree}"
26  else
27    git worktree add -b "${branch}" "${worktree}" "${BASE_BRANCH}"
28  fi
29
30  (cd "${worktree}/frontend" && bun install --frozen-lockfile) &
31  (cd "${worktree}/backend"  && uv sync) &
32  wait
33}
34
35run_lane() {
36  local id="$1"
37  local worktree="${WORKTREE_DIR}/lane-${id}"
38  local log="${LOG_DIR}/lane-${id}.log"
39  local prompt="<redacted prompt built from plan + conventions>"
40
41  codex exec --dangerously-bypass-approvals-and-sandbox -C "${worktree}" "${prompt}" > "${log}" 2>&1
42}
43
44create_pr() {
45  local id="$1"
46  local branch="${TASK_BRANCH[$id]}"
47  local title="${TASK_TITLE[$id]}"
48  local worktree="${WORKTREE_DIR}/lane-${id}"
49
50  git -C "${worktree}" push -u origin "${branch}"
51  gh pr create --base "${BASE_BRANCH}" --head "${branch}" --draft --title "${title}" --body "<templated body>"
52}

References

• Codex docs hub: https://developers.openai.com/codex
• Codex CLI overview: https://developers.openai.com/codex/cli
• Codex CLI features: https://developers.openai.com/codex/cli/features
• Codex multi-agent docs: https://developers.openai.com/codex/multi-agent
• Codex security/sandbox docs: https://developers.openai.com/codex/security
• Codex config basics: https://developers.openai.com/codex/config-basic
• Codex config reference: https://developers.openai.com/codex/config-reference
• Codex CLI GitHub README: https://github.com/openai/codex/blob/main/README.md
• Ralph loop agent (Vercel Labs): https://github.com/vercel-labs/ralph-loop-agent
• Ralph from first principles (Geoffrey Huntley): https://www.youtube.com/watch?v=4Nna09dG_c0
• Git worktree docs: https://git-scm.com/docs/git-worktree

Before we start, here’s a link to one of the best free books on Git: Pro Git Book

What is Version Control?

When working on a project, we often need to keep track of changes made to the code. Version control systems help us track and reconcile changes across different versions of our codebase.

Think of your codebase as a tree. Each change you make can create a new branch in the tree. It’s up to you to decide if your changes are good enough to become part of the main branch. But why a tree? Because we have a single source of truth (the main branch) based on which we can reconcile all changes.

Imagine the source of truth is a single branch called main. When you want to work on a new feature, you create a branch from main, make your changes in that branch, and once you’re done, you can merge the branch back into main.

This approach allows us to:

1. Work on multiple features in parallel
2. Enable multiple people to work on the same codebase simultaneously
3. Revert to previous stable states if something goes wrong

Getting Started

First, download Git from here and install it.

In this guide, we’ll cover:

1. Setting up Git credentials
2. Creating a new repository
3. Understanding the staging area and making commits
4. Working with branches
5. Merging branches
6. Working with remote repositories
7. Common Git commands and workflows

1. Setting Up Git Credentials

Before you start using Git, configure your name and email. These will be associated with all your commits.

1git config --global user.name "Your Name"
2git config --global user.email "your.email@example.com"

You can verify your configuration with:

1git config --list

2. Creating a New Repository

Navigate to the directory where you want to create the repository. You can either:

• Initialize an existing directory as a Git repository
• Create a new directory and then initialize it

1# Option 1: Initialize current directory
2git init
3
4# Option 2: Create new directory and initialize
5mkdir my-project
6cd my-project
7git init

3. Understanding the Staging Area and Making Commits

Git uses a three-stage workflow:

1. Working Directory: Your files as they exist on disk
2. Staging Area: Files you’ve marked to be included in the next commit
3. Repository: Committed snapshots of your project

Let’s create a file and commit it:

1# Create a new file
2echo "Hello, World!" > hello.txt
3
4# Stage the file (add it to the staging area)
5git add hello.txt
6
7# Commit the changes with a descriptive message
8git commit -m "Add hello.txt file"

Key Commands:

• git status - See which files are modified, staged, or untracked
• git add <file> - Stage a specific file
• git add . - Stage all changes in the current directory
• git commit -m "message" - Commit staged changes with a message

4. Working with Branches

Branches allow you to work on features, experiments, or fixes without affecting the main codebase.

Create and switch to a new branch:

1git checkout -b feature1

This is equivalent to:

1git branch feature1      # Create the branch
2git checkout feature1    # Switch to the branch

Modern alternative (Git 2.23+):

1git switch -c feature1   # Create and switch

Make changes in the new branch:

1echo "Hello, World! in feature1" > hello.txt

View all branches:

1git branch                # List local branches
2git branch -a            # List all branches (local and remote)

5. Committing Changes to a Branch

1git add hello.txt
2git commit -m "Update hello.txt in feature1 branch"

6. Merging Branches

Once your feature is complete, merge it back into main:

1# Switch back to main branch
2git checkout main
3
4# Merge feature1 into main
5git merge feature1

Note: If there are no conflicts, Git will automatically create a merge commit. If conflicts occur, you’ll need to resolve them manually.

7. Working with Remote Repositories

Remote repositories allow you to collaborate with others and back up your code.

Add a remote repository:

First, create a new repository on a platform like GitHub, GitLab, or Bitbucket. Then copy the repository URL and add it as a remote:

1git remote add origin <remote-repository-URL>

View remote repositories:

1git remote -v              # List all remotes with URLs

Update remote URL (if needed):

1git remote set-url origin <new-URL>

8. Pushing Changes to Remote

Push your local commits to the remote repository:

1git push -u origin main

The -u flag sets up tracking, so future pushes can be done with just git push.

Push to a specific branch:

1git push origin feature1

9. Pulling Changes from Remote

git pull fetches changes from the remote and merges them into your current branch:

1git pull origin main

Note: git pull is equivalent to git fetch followed by git merge.

10. Fetching Changes from Remote

git fetch downloads changes from the remote without merging them:

1git fetch origin

This is useful when you want to see what changes exist on the remote before merging them. After fetching, you can review changes with:

1git log origin/main..main    # See commits on remote
2git diff origin/main          # See differences

Additional Useful Commands

Viewing History and Changes

1git log                      # View commit history
2git log --oneline            # Compact one-line view
3git log --graph --oneline    # Visual branch history
4git diff                     # See unstaged changes
5git diff --staged            # See staged changes
6git show <commit-hash>       # Show details of a specific commit

Undoing Changes

1git restore <file>           # Discard changes in working directory
2git restore --staged <file>  # Unstage a file
3git reset HEAD~1             # Undo last commit (keeps changes)
4git reset --hard HEAD~1      # Undo last commit (discards changes) - use with caution!

Working with .gitignore

Create a .gitignore file to exclude files from version control:

1# Example .gitignore
2node_modules/
3*.log
4.env
5.DS_Store

Cloning a Repository

To get a copy of an existing repository:

1git clone <repository-URL>

This creates a new directory with the repository name and downloads all files and history.

Common Workflows

Typical workflow:

1. git pull - Get latest changes
2. git checkout -b feature-name - Create feature branch
3. Make changes and git add files
4. git commit -m "message" - Commit changes
5. git push origin feature-name - Push to remote
6. Create pull/merge request on platform
7. After review, merge to main
8. git checkout main && git pull - Update local main

Tips and Best Practices

1. Write clear commit messages: Describe what and why, not how
2. Commit often: Small, logical commits are easier to review and revert
3. Pull before push: Always pull latest changes before pushing
4. Use branches: Keep main stable, work on features in branches
5. Review before merging: Check your changes with git diff and git status