Skip to content
roguelite labsAnthony Spezzano ↗

Parallel Worktrees

2 min · workflow

Git worktrees let you check out multiple branches from the same repository simultaneously, each in its own directory, sharing a single .git object store. Combined with multiple AI coding agent instances, this enables parallel work on independent tasks without context-switching overhead.

What Worktrees Enable

Normally, switching branches means stashing, checking out, and losing the working state of the previous branch. Worktrees eliminate that by keeping each branch's working tree in a separate directory. Two branches can be fully checked out, dirty state and all, at the same time.

# Add a worktree for a new branch
git worktree add ../roguelitelabs-feat-embeddings -b feat/embeddings

# List active worktrees
git worktree list
# /home/exedev/roguelitelabs           abc1234 [main]
# /home/exedev/roguelitelabs-feat-embeddings  def5678 [feat/embeddings]

# Remove when done
git worktree remove ../roguelitelabs-feat-embeddings

Each worktree is an independent directory. Editors, terminal sessions, and agents operate on it independently.

The Dmux Pattern

The dmux pattern (distributed multiplexing) runs multiple Claude Code instances, each in its own worktree, working on separate tasks simultaneously.

Setup:

  1. Identify tasks that are genuinely independent — no shared files, no sequential dependencies.
  2. Create one worktree per task with a descriptive name.
  3. Launch a Claude Code session in each worktree directory (claude or claude --dir <path>).
  4. Each agent works on its branch without interfering with the others.
  5. When tasks complete, review and merge normally.
# Example: three parallel tasks
git worktree add ../rll-feat-embeddings   -b feat/embeddings
git worktree add ../rll-feat-guardrails   -b feat/guardrails
git worktree add ../rll-fix-rag-retrieval -b fix/rag-retrieval

# Open three terminal windows, launch Claude Code in each
# cd ../rll-feat-embeddings && claude
# cd ../rll-feat-guardrails && claude
# cd ../rll-fix-rag-retrieval && claude

When This Pays Off

Good fit:

  • Large independent tasks: adding a new feature, writing a full module, refactoring an isolated component
  • Parallel exploration: trying two implementation approaches and comparing results
  • Background tasks: running a long eval or data migration in one worktree while working interactively in another

Poor fit:

  • Tightly coupled changes that touch the same files — merge conflicts eliminate the benefit
  • Short tasks (< 15 minutes) — worktree setup overhead isn't worth it
  • Tasks that depend on each other sequentially — parallel execution doesn't help

Path Conventions

Keep worktrees adjacent to the main repo with a consistent naming scheme:

/home/exedev/
  roguelitelabs/             # main worktree
  roguelitelabs-feat-X/      # feature worktrees
  roguelitelabs-fix-Y/       # fix worktrees
  roguelitelabs-exp-Z/       # experiment worktrees

This keeps ls readable and makes the relationship between worktrees obvious.

Teardown

Always remove worktrees after merging. Orphaned worktrees are confusing and waste disk space. git worktree prune removes stale entries for worktrees whose directories no longer exist.

git worktree remove ../roguelitelabs-feat-embeddings
git worktree prune  # clean up stale refs

Sources