Claude Code Worktrees: Isolated Development in Parallel Branches

Claude Code integrates worktrees natively. It can create a worktree, work in it, make commits, and return to the main directory, all without touching your current branch.

The problem they solve

Imagine you're working on a feature and an urgent bug appears. You have two classic options:

• Option A: stash, switch branches, fix the bug, come back. Risk of losing changes, conflicts on return
• Option B: clone the repo in another directory. Duplicate all git history, consume disk

Worktrees are option C: create a lightweight working directory on another branch. No stash, no cloning, no risk. Git shares the .git directory across all worktrees.

Git worktree: basic concepts

Before seeing how Claude Code uses worktrees, you need to understand what they are at the git level. If you already master git worktree, skip to the next section.

What is a worktree: Normally, a git repository has a single working directory (working tree). That's the directory where you see your files. With git worktree, you can create additional working directories, each linked to a different branch.

How it works internally:

• All worktrees share the same .git directory (the history)
• Each worktree has its own HEAD, index and working tree
• You can't have two worktrees on the same branch (git prevents it)
• Commits in one worktree are immediately visible from any other

Analogy: Think of your repository as a library. Normally you can only have one book open at a time (one branch). Worktrees let you have several books open simultaneously, each on a different page, but all belonging to the same library.

# Estructura típica con worktrees
mi-proyecto/              # worktree principal (main)
mi-proyecto-feature/      # worktree en rama feature/dashboard
mi-proyecto-hotfix/       # worktree en rama hotfix/login-bug

# Los tres comparten: mi-proyecto/.git/

How they work in Claude Code

Claude Code can use worktrees in two ways:

• Automatic: when it detects it needs to work on a separate branch without affecting your current work
• Manual: when you explicitly ask it to create a worktree to isolate changes

Internally, Claude Code uses the EnterWorktree and ExitWorktree tools to move between working directories. When entering a worktree:

1. Creates the worktree in a sibling directory to the project
2. Changes its working directory to the new worktree
3. Executes all operations there (edit, create, delete files)
4. Commits changes to the worktree's branch
5. Exits the worktree and returns to your original directory

Your main branch stays intact throughout the process. No stash, no unsaved changes, no risk.

Creating and managing worktrees

Creating worktrees with git is simple. Claude Code does it for you, but it's useful to understand the commands:

# Crear un worktree en una nueva rama
git worktree add ../mi-proyecto-fix hotfix/login-bug

# Crear worktree desde una rama remota
git worktree add ../mi-proyecto-pr origin/feature/new-ui

# Listar worktrees activos
git worktree list

# Eliminar un worktree cuando termines
git worktree remove ../mi-proyecto-fix

# Limpiar referencias a worktrees eliminados manualmente
git worktree prune

Each worktree is a complete directory with all project files in the selected branch's state. You can open it with any editor, run tests, and make independent commits.

Worktrees vs branches: when to use each

Creating a branch and switching to it (git checkout -b) vs creating a worktree (git worktree add). Both create a branch, but the experience is different:

Use normal branches when:

• You'll work on one thing at a time (sequentially)
• You have no uncommitted changes on your current branch
• The change is quick and you don't need context from the previous branch
• You don't need to compare results side by side

Use worktrees when:

• You have work in progress you don't want to stash or commit
• You need to work on two things at once (in parallel)
• You want to compare two implementations side by side
• The hotfix is complex and may take time, but you don't want to block your feature
• You use Claude Code with subagents and each needs its own isolated space

Practical rule: if you're about to git stash, a worktree is probably a better option.

Parallel development workflow

The real power of worktrees appears when you use them for parallel development. This is the workflow I use in real projects:

# Workflow: desarrollo paralelo con Claude Code

# 1. Estás trabajando en feature/dashboard (worktree principal)
# 2. Llega un bug report urgente

# Le dices a Claude Code:
> Crea un worktree para arreglar el bug de login.
 Rama: hotfix/login-fix. No toques mi trabajo actual.

# 3. Claude Code crea el worktree, entra, arregla, commitea, sale
# 4. Tú sigues en feature/dashboard como si nada

# 5. Cuando quieras, haces merge del hotfix
git merge hotfix/login-fix

# 6. Limpias el worktree
git worktree remove ../mi-proyecto-hotfix

This workflow scales. You can have 3-4 active worktrees if you work on a project with multiple fronts. Each isolated, each with its own context.

Practical examples

Example 1: Hotfix without interrupting your work

# Le pides a Claude Code:
"Hay un bug en el login. Arréglalo en un worktree
sin tocar mi rama actual (feature/dashboard)"

# Claude Code:
# 1. Crea worktree en ../proyecto-hotfix desde main
# 2. Entra al worktree
# 3. Arregla el bug, hace commit
# 4. Sale del worktree
# 5. Tu rama feature/dashboard sigue intacta

Example 2: Test two approaches in parallel

# Explorar dos soluciones simultáneamente:
"Crea dos worktrees: uno con la solución usando Redis
y otro con la solución usando PostgreSQL.
Implementa ambos y compara rendimiento"

Example 3: PR review in worktree

# Revisar código de un compañero sin cambiar de rama:
"Haz checkout del PR #42 en un worktree,
analiza el código y dame un review"

Example 4: Gradual migration

# Migrar de una librería a otra sin romper nada:
"Crea un worktree en rama migrate/react-19.
Actualiza todas las dependencias y corrige los
breaking changes. Quiero poder comparar con la
versión actual."

Worktrees + Subagents: advanced combo

The combination of worktrees with subagents is the most powerful productivity technique in Claude Code. Each subagent works in its own worktree, with total isolation.

# Ejemplo: refactoring paralelo
"Necesito refactorizar 3 módulos independientes.
Crea un worktree por módulo y trabaja en los tres
en paralelo:
- Worktree 1: refactor/auth (módulo de autenticación)
- Worktree 2: refactor/payments (módulo de pagos)
- Worktree 3: refactor/notifications (módulo de notifs)

Cada uno debe pasar tests antes de commitear."

What happens internally:

1. Claude Code creates 3 worktrees
2. Launches one subagent per worktree
3. Each subagent works on its module without interfering with others
4. Each runs tests on its branch
5. All three can finish at different times
6. You decide when to merge each one

The result: 3 independent PRs, each testable separately, created in parallel. What would take 3 sequential sessions is resolved in one.

Real-world scenarios

Scenario 1: Sprint with multiple features. You're in a sprint with 4 assigned tickets. Each is a small feature. Instead of doing them sequentially (branch, code, PR, next), you create 4 worktrees and work on all with Claude Code. By end of day you have 4 PRs ready for review.

Scenario 2: Production debugging. A client reports a bug. You need to reproduce it on the exact version they have (v2.3.1), but you're working on v2.5. Create a worktree pointing to tag v2.3.1, reproduce the bug, find the cause, and apply the fix both in the old version worktree and in main.

Scenario 3: Performance comparison. You're optimizing a SQL query. Create one worktree with implementation A (composite index) and another with implementation B (materialized view). Run benchmarks on both and compare results side by side before deciding which to merge.

Scenario 4: New member onboarding. A new developer joins the team. Create a worktree on a "playground" branch where they can experiment risk-free. Claude Code guides them inside that worktree and any disaster is deleted without affecting the team.

Cleanup and maintenance

Worktrees accumulate directories if you don't clean them. Keep your system organized:

# Ver todos los worktrees activos
git worktree list
# Output:
# /Users/tu/proyecto       abc1234 [main]
# /Users/tu/proyecto-fix   def5678 [hotfix/login]
# /Users/tu/proyecto-feat  ghi9012 [feature/dashboard]

# Eliminar un worktree que ya no necesitas
git worktree remove ../proyecto-fix

# Si borraste el directorio manualmente (rm -rf),
# limpia las referencias huérfanas
git worktree prune

# Eliminar también la rama si ya la mergeaste
git branch -d hotfix/login

# Script de limpieza rápida (limpia todo lo mergeado)
git worktree list --porcelain | grep "branch" | \
 while read line; do
   branch=$(echo $line | cut -d'/' -f3-)
   if git branch --merged main | grep -q "$branch"; then
     echo "Candidato a limpiar: $branch"
   fi
 done

Good practice: at the end of each workday, run git worktree list. If you see worktrees you no longer need, delete them. A clean repository is a fast repository.

Best practices

• Clean finished worktrees: don't accumulate directories. Run git worktree prune periodically
• Descriptive names: use ../project-hotfix-login instead of ../wt1
• Don't modify the same file: if two worktrees touch the same file and you then merge, you'll have conflicts
• Worktree to experiment: try risky ideas in a worktree. If it doesn't work, delete the directory and done
• CI/CD: combine worktrees with headless execution for pipelines testing multiple configurations in parallel
• Commit before leaving: always commit (or stash) in a worktree before leaving it. Unsaved changes in an abandoned worktree are hard to recover
• One worktree per task: don't reuse worktrees for different tasks. The cost of creating a new one is negligible

FAQ

What is a worktree in Claude Code?

A worktree is an additional git working directory that allows having multiple branches checked out simultaneously. Claude Code uses them to work on isolated changes without affecting your main branch. Integration is native: Claude Code creates, enters, works and exits worktrees automatically.

What's the difference between subagents and worktrees?

Subagents are parallel execution threads that can share the same directory. Worktrees are separate git directories where each has its own branch. You can combine both: one subagent per worktree for maximum isolation and parallelism.

Do worktrees consume more disk?

Minimally. Git worktrees share the .git directory (which contains all history), so only the working files (source code) are duplicated. For a project with 100MB of history and 5MB of code, an extra worktree takes only 5MB.

Can I have multiple active worktrees at once?

Yes, you can have as many worktrees as you need. The only restriction is that each worktree must be on a different branch: you can't have two worktrees pointing to the same branch simultaneously.

What happens if I delete a worktree without merging?

The commits you made in that worktree still exist in git history (on the associated branch). Only the working directory disappears. You can recover the changes by checking out that branch at any time, either in a new worktree or with git checkout.

Next step

Worktrees are a fundamental tool for isolated development. Combine them with subagents for maximum parallelism, configure settings.json to automate their creation, and explore headless mode to integrate them into your CI/CD pipelines.

If you're new to Claude Code, start with the beginners guide before exploring worktrees. They're an intermediate-advanced technique that makes more sense when you've mastered the fundamentals.