Stop Watching One Codex Agent Work

Watching one AI agent work is like paying for five employees and only giving one of them a desk. If you run a single Codex session at a time, you're queueing work that could run in parallel. git worktree checks out a branch into its own folder — same repository, separate working directory — so you can point a different Codex agent at each one without them stepping on each other's files.

The problem with one folder, one agent

A normal git checkout gives you one working directory tied to one branch at a time. Switch branches and every file on disk changes with it. That breaks down the moment you want two AI agents working simultaneously on the same repo — they'd both be editing files on disk on whatever branch happens to be checked out, colliding constantly. Cloning the repo again works but duplicates the full .git history and dependencies for every parallel session — wasteful, and easy to let drift.

What a worktree actually is

A git worktree is a second working directory linked to the same repository. Your original folder stays exactly where it is, on whatever branch it was on — untouched. The new worktree is a fresh folder, checked out to a new (or existing) branch, sharing the same underlying .git object database. You get isolated file trees without duplicating the repository's history or storage.

Creating one

One command creates a worktree, a new folder, and a new branch together:

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

This checks out a new branch feature-x into a sibling folder ../feature-x. Your original folder is untouched and stays on main. Run it again with a different path and branch name for a third folder, a third isolated space, all pointing at the same repository history.

Running Codex in parallel

1. Open a terminal in the new worktree folder.
2. Initialize/start Codex there and give it the feature to work on.
3. Repeat for a second folder, a third, as many as you have features in flight.

Each Codex session operates entirely within its own worktree — reading and writing files in that folder, running its own tests, committing to its own branch — with zero risk of touching a file another agent is mid-edit on, since they're not sharing a directory. You're now running agents in parallel instead of queueing them one after another. This is supported directly in Codex's tooling too: the desktop app offers a "hand off to a worktree" option so agents don't override each other's files.

Cleaning up after a merge

git worktree remove ../feature-x
git branch -d feature-x

Removing the worktree first clears the linked working directory; deleting the branch afterward is then a normal, safe operation. Skipping the removal step leaves a stale folder pointing at a branch that no longer needs to exist — clutter that adds up fast running several agents a week.

When this is worth doing

• Front-end and back-end changes landing together — one worktree per side, two agents working in lockstep.
• Several small, independent features at once — a worktree per feature keeps each agent's context scoped to one piece of work, producing cleaner diffs than one agent juggling multiple unrelated changes.
• Reviewing finished work instead of babysitting — your job shifts from watching one agent type to periodically checking in on several.

Pitfalls

• Forgetting to remove worktrees after merging. They don't clean themselves up.
• Chunking features too large. Parallel agents are only manageable if each piece finishes and reviews in a reasonable window — five worktrees on five sprawling features is still five things you can't track.
• Assuming worktrees isolate dependencies too. They isolate the file tree and branch, not installed packages or environment state — set those up per worktree.

Resources

• git-scm.com — git worktree reference