Codex and Git Worktrees for Parallel Sessions

Running two Codex sessions against the same repository at once, in the same working directory, is a recipe for both sessions stepping on each other's uncommitted changes. Git worktrees solve exactly this problem, and they're a natural fit for parallel agentic sessions specifically because each worktree is a genuinely separate working directory sharing the same underlying repository history.

Why worktrees fit this use case better than separate clones

A separate full clone per parallel task works, but it duplicates the entire repository on disk and needs its own remote tracking, its own fetches, its own everything kept in sync. A worktree shares the same .git data as the original checkout while giving each task its own independent working directory — smaller footprint, and any commits made in one worktree are immediately visible to git log in every other worktree of the same repository, since they're all reading the same underlying history.

Starting a session per worktree

Once a worktree exists for a given branch or task, starting a separate Codex session rooted in that worktree's directory keeps that session's edits, its sandbox boundary, and its sense of "the project" scoped to that one worktree specifically. Two sessions in two worktrees can work on genuinely independent tasks — a bug fix in one, a feature branch in another — without either one seeing the other's uncommitted, in-progress changes, because they're different directories on disk even though they share history.

The protected .git path still applies, and it's worth understanding why

Every worktree's .git is a pointer file, not a real directory — it names the actual git data, which lives with the original checkout. Codex's protection on .git follows that resolution rather than stopping at the pointer file's literal bytes, so every worktree's protected boundary resolves back to the same underlying git data, not a separate one per worktree. That's a feature for this exact setup: it means no worktree can be used to route around the protection that applies to the shared history all of them are built on.

Merge conflicts are still your problem, not Codex's

Worktrees prevent two sessions from clobbering each other's uncommitted work in the same directory — they don't prevent two branches from eventually needing to merge, and if both sessions touch overlapping code, that merge still has to happen the normal way, with the normal potential for conflicts. Treat parallel worktree sessions as parallel branches of work that will need reconciling later, not as a way to avoid ever having to think about how the two tasks' changes interact.

Naming and organizing worktrees for sanity

A worktree per active task, named clearly enough that you can tell at a glance which is which — the branch name is usually sufficient — avoids the confusion of several similarly-named directories on disk with no obvious mapping back to what each one is actually for. This matters more the longer you run parallel sessions; a setup that made sense with two worktrees active can become genuinely hard to track with five or six unless the naming was deliberate from the start.

Cleaning up after a task finishes

An abandoned worktree left on disk after its branch has been merged or discarded is just clutter — worth removing explicitly once a task is done, rather than letting worktrees accumulate indefinitely. Because they share the underlying git data with the main checkout, an old worktree isn't actively harmful the way a stale full clone with diverged history might be, but it's still worth tidying up so a future "which of these am I actually still using" question has an easy answer.

Cost and context are still per-session, not per-worktree

Running several parallel sessions across several worktrees means several separate, independent contexts accumulating in parallel — each one is its own session for pricing, rate-limit, and long-context-threshold purposes, not shared or pooled across worktrees. A team running many parallel worktree sessions should budget for that multiplication explicitly, the same way any other parallel workload gets budgeted, rather than assuming worktrees are free just because they share disk space efficiently.

Rate limits across parallel sessions

Because parallel worktree sessions are still calling the same account, they draw down the same shared rate-limit pool for whatever model each is using — several sessions running concurrently against the same model can collectively approach a ceiling that any single session alone wouldn't have. This is worth checking against the rate-limit tier planner before scaling up how many parallel sessions you routinely run, especially if each one tends to make frequent, small requests rather than occasional large ones.

Setting up a worktree in practice

Creating a worktree for a new task is a small, mechanical step — a new directory, checked out against a new or existing branch, sharing the parent repository's history — and it's worth scripting if you find yourself doing it often enough that the exact commands become a point of friction. A short helper script that creates a worktree, names it consistently, and optionally starts a Codex session rooted in it removes the setup cost entirely, turning "start a new parallel task" into a single command rather than a small ritual of manual steps each time.

When worktrees are the wrong tool

Not every parallel-seeming task actually benefits from a separate worktree — two small, quick edits to unrelated files in the same area of the codebase are often just as easily done sequentially in one session as they are set up as two parallel worktree sessions, and the setup and cleanup overhead of a worktree isn't free. Worktrees earn their keep specifically when tasks are large enough, or long-running enough, that genuine parallelism outweighs the small fixed cost of managing more than one working directory at once.