Worktree, branch, or session: parallelism patterns for AI dev

When you run two AI agents on the same codebase simultaneously, they'll fight unless you isolate their working state. The three isolation patterns — branches, worktrees, separate clones — each have a place. This post is the practical decision guide.

TL;DR

The three patterns

Pattern 1: Branch (no isolation, just a git ref)

cd ~/dev/repos/main-app
git checkout -b feat/auth-jwt
# agent works here

What you have: one working directory, one checked-out branch. Switch branches to switch contexts.

Strengths: simplest, what everyone already knows.

Weaknesses: only one branch checked out at a time. Two agents trying to work simultaneously will checkout-fight.

Use when: you have one agent at a time, or two agents whose work is so quick that they can take turns.

Pattern 2: Worktree (light isolation, shared .git)

cd ~/dev/repos/main-app
git worktree add ~/dev/sessions/2026-04-22-auth-rewrite/repo feat/auth-jwt
git worktree add ~/dev/sessions/2026-04-22-launch-post/repo feat/launch-post

What you have: multiple working directories under ~/dev/sessions/, each with its own checked-out branch. They share the .git/ of the main repo.

Strengths: parallel checkouts (different branches simultaneously), no .git duplication, fast to set up.

Weaknesses: can't checkout the same branch in two worktrees. Some IDE indexers initially confused.

Use when: 2-5 parallel agents on the same repo. The default for AI fleet workflows.

Pattern 3: Separate clone (full isolation)

git clone <url> ~/dev/sessions/2026-04-22-auth-rewrite/repo
git clone <url> ~/dev/sessions/2026-04-22-launch-post/repo

What you have: completely separate git repositories, sharing only the remote upstream.

Strengths: full isolation. One clone can have a totally different config, different remote, different submodule state.

Weaknesses: duplicates .git/ (wasteful for large repos), slower setup, easier to drift.

Use when: genuinely divergent work, different remote configs, or "I want zero possibility of cross-pollution."

Concrete examples

Example 1: Two agents, two features

You have main app, want one agent rewriting auth and another drafting docs:

cd ~/dev/repos/main-app

# Pre-create branches
git branch feat/auth-jwt
git branch docs/launch-post

# Spawn worktrees
git worktree add ~/dev/sessions/2026-04-22-auth-rewrite/repo feat/auth-jwt
git worktree add ~/dev/sessions/2026-04-22-launch-post/repo docs/launch-post

Now two agents can work simultaneously. Each has its own working directory, its own branch, no conflict.

Example 2: Three agents on different bug fixes

git worktree add ~/dev/sessions/fix-bug-a/repo fix/bug-a
git worktree add ~/dev/sessions/fix-bug-b/repo fix/bug-b
git worktree add ~/dev/sessions/fix-bug-c/repo fix/bug-c

Three parallel investigations. Each agent commits to its own branch. PRs can be reviewed in parallel.

Example 3: Long-running fork

You've decided to experimentally fork the codebase to try a major redesign. Don't worktree — clone:

git clone --branch experimental-redesign <url> ~/dev/experimental/main-app

This stays separate. You may never merge back; the worktree pattern would imply more entanglement than you want.

Mental model: branches are refs, worktrees are checkouts

Branches in git are just pointers to commits. They cost nothing.

Worktrees are physical checkouts — actual files on disk. They cost disk space (one working tree per worktree) but no duplicate .git.

Clones are full repos — duplicate .git plus working tree.

For parallelism, you need physical isolation (worktrees or clones). Branches alone aren't enough.

When worktrees go wrong

A few common issues and the fixes:

"fatal: is already checked out at "

You can't have the same branch in two worktrees. Either rename the second worktree's branch:

cd ~/dev/sessions/foo/repo
git checkout -b foo-variant

Or remove the conflicting worktree.

Submodules don't show up

Some submodule configurations don't auto-init in worktrees. Workaround:

cd ~/dev/sessions/<session>/repo
git submodule update --init --recursive

IDE indexer confused

VS Code, Cursor, Xcode sometimes get confused when two worktrees have the same .git. Restart the IDE; or add the new worktree as a new project root if the IDE supports multi-root.

Worktree references stale

After manually deleting a worktree directory:

git worktree prune

This cleans up references. Otherwise git worktree list shows ghost entries.

When clones go wrong

Less common but worth noting:

Forgot to fetch upstream changes

A long-lived clone diverges from upstream if you don't git fetch regularly. Worktrees share fetches; clones don't.

Disk space

A 500MB repo cloned 5 times = 2.5GB. Worktrees of the same repo = 500MB + (500MB worktree size × 5) = ~3GB but shared .git so much less duplicate. Specifically the .git/ itself is the chunky part — worktrees share it; clones don't.

For very large repos this matters.

Integration with cmux

Each parallel agent should have its own cmux session pointing at its working directory:

# Setup worktrees
git worktree add ~/dev/sessions/auth-rewrite/repo feat/auth-jwt
git worktree add ~/dev/sessions/launch-post/repo docs/launch-post

# Spawn cmux sessions, each rooted in its worktree
cmux create rewrite-auth --dir ~/dev/sessions/auth-rewrite/repo
cmux create draft-launch-post --dir ~/dev/sessions/launch-post/repo

Now each cmux session's working directory is the worktree. Agents stay in their lane.

mq-dir's CMUX sidebar shows both sessions; click to navigate the focused pane.

Cleaning up after merge

When feat/auth-jwt lands:

git worktree remove ~/dev/sessions/2026-04-22-auth-rewrite/repo
git branch -d feat/auth-jwt   # if merged

The worktree directory disappears. The branch is deleted (assuming merged).

For unmerged abandoned work:

git worktree remove --force ~/dev/sessions/<session>/repo
git branch -D <branch>

--force and -D because the work isn't merged. Make sure you really want to throw it away.

Anti-patterns

A few things not to do:

Run two agents on main simultaneously

Just no. They'll commit-conflict and confuse each other. Always use feature branches.

Use a single worktree for "the AI" generally

If "the AI worktree" handles all your AI sessions, the agents step on each other. One worktree per session.

Worktree without an actual session goal

Spawning a worktree before knowing what you'll do invites accumulation. Better: define the session (CLAUDE.md, name, goal), then spawn the worktree as part of setup.

Forget worktrees exist

git worktree list is your friend. Run it weekly to see what's accumulated. Old worktrees waste disk and create confusion.

Decision flow

Need parallel AI work on same codebase?
│
├── 1 agent at a time → BRANCH is enough
│
├── 2-5 parallel agents on same repo → WORKTREE per agent
│
├── Genuinely divergent / different remotes → SEPARATE CLONE
│
└── Throwaway experiment → BRANCH (just be careful)

Verdict

For AI fleet workflows on a single repository, worktree per agent is the right default. It gives you the isolation you need (separate working trees per agent) without the cost of separate clones (duplicate .git, disk waste).

The full pattern:

• One worktree per concurrent AI session.
• One cmux session per worktree.
• One mq-dir pane visualizing each worktree.
• One CLAUDE.md per session declaring scope.

This is how you run 5 parallel agents without them fighting. Setup is one-time per repo; payoff is daily.

mq-dir is free, MIT, and pairs cleanly with this workflow.