Guia completa de Claude Worktree

Introduccion

Cuando utiliza Claude Code para tareas complejas, es posible que haya enfrentado esta situacion: tiene tres tareas independientes que manejar, pero ejecutar multiples instancias de Claude en el mismo directorio provoca conflictos de codigo — un Agent modifica un archivo mientras otro tambien lo esta editando, y al momento de fusionar todo se convierte en un desastre.

En febrero de 2025, Anthropic lanzo el comando --worktree, transformando completamente esta situacion. Ahora puede ejecutar claude -w feature-1, claude -w feature-2 y claude -w bugfix-1 en tres terminales separadas, con cada Agent trabajando en un entorno aislado sin interferir con los demas.

Comprender Worktree

Imagine que es un arquitecto disenando tres habitaciones diferentes al mismo tiempo. El enfoque tradicional seria dibujar en el mismo plano, lo cual facilmente genera confusion al hacer cambios. El enfoque de Worktree le proporciona tres planos independientes, cada uno dedicado al diseno de una habitacion, para luego fusionarlos en el plano principal.

Desde el punto de vista tecnico, Worktree es una funcionalidad nativa de Git. El comando --worktree de Claude Code encapsula esta funcionalidad para hacerla mas simple — un solo comando crea el entorno aislado, inicia la instancia de Claude y realiza la limpieza automatica al finalizar.

Por que no simplemente hacer multiples Clone

Quizas se pregunte: ¿por que no simplemente clonar el codigo multiples veces?

Worktree comparte la misma base de datos .git, todo el historial de commits e informacion de ramas es compartido. Esto significa que un commit creado en un worktree es inmediatamente visible desde los demas worktrees.

Cuando utilizar Worktree

Antes de comenzar, evalue si su tarea es adecuada para usar worktree.

Regla general: si la tarea requiere mas de 30 minutos, considere usar worktree. Para tareas cortas, usar worktree puede ser contraproducente — crear el entorno, instalar dependencias y fusionar al final puede tomar mas tiempo que la tarea en si. Sin embargo, para tareas que requieren trabajo profundo, el aislamiento de worktree es muy valioso.

Requisitos previos

Antes de usar worktree, asegurese de cumplir con las siguientes condiciones:

Flujo de trabajo completo: de la creacion a la limpieza

A continuacion, recorreremos el flujo completo desde la creacion del Worktree hasta la limpieza final, siguiendo el orden real de desarrollo.

Paso 1: Crear el Worktree

Crear desde la rama remota predeterminada

Utilice el parametro -w o --worktree para iniciar Claude:

# Crear un worktree llamado "feature-auth" e iniciar Claude
claude -w feature-auth

# Generar un nombre aleatorio automaticamente (como "bright-running-fox")
claude -w

Este comando realiza cuatro acciones:

1. Crea un nuevo directorio de trabajo en <repo>/.claude/worktrees/feature-auth/
2. Crea una nueva rama llamada worktree-feature-auth
3. Hace checkout del codigo desde la rama remota predeterminada (como origin/main u origin/master) — tenga en cuenta que no es la rama en la que se encuentra actualmente
4. Inicia Claude Code en el nuevo directorio

Todos los worktrees se ubican en el directorio .claude/worktrees/:

your-project/
├── .claude/
│   └── worktrees/
│       ├── feature-auth/      ← primer worktree
│       ├── bugfix-123/        ← segundo worktree
│       └── refactor-api/      ← tercer worktree
├── src/
└── package.json

Se recomienda agregar esta ruta a .gitignore:

# .gitignore
.claude/worktrees/

Crear desde la rama actual o una rama especifica

-w siempre hace checkout desde la rama remota predeterminada y actualmente no soporta especificar una rama base. Si desea crear un worktree basado en la rama actual (o una rama especifica), hay tres formas:

Forma 1: Creacion manual con Git

# Crear worktree basado en el HEAD actual
git worktree add -b my-feature .claude/worktrees/my-feature HEAD

# O basado en una rama especifica
git worktree add -b hotfix .claude/worktrees/hotfix origin/release-v2

# Luego iniciar Claude en ese directorio
cd .claude/worktrees/my-feature && claude

Esta forma le da control total — puede crear worktrees basados en cualquier rama o cualquier commit, y el directorio de trabajo comienza en la rama correcta desde el inicio. La documentacion oficial tambien recomienda: "Si necesita mas control sobre ramas y ubicaciones, cree el worktree directamente con Git y luego ejecute Claude en ese directorio."

Forma 2: Crear dentro de la conversacion (recomendado)

En una sesion existente de Claude, simplemente pida a Claude que cree el worktree:

> 从当前分支开启一个worktree
> start a worktree

A diferencia del comando -w, un worktree creado dentro de la conversacion se basara automaticamente en la rama actual, no en la rama remota predeterminada. Claude completara automaticamente la creacion del worktree y cambiara a el, sin necesidad de ejecutar manualmente ningun comando Git. Si ya esta trabajando en una rama feature, esta es la forma mas conveniente — con una sola instruccion obtiene un entorno aislado basado en su rama actual.

Forma 3: Crear primero con -w, luego cambiar de rama en la sesion

Primero cree el worktree con claude -w, y una vez dentro de la sesion pida a Claude que cambie a la rama objetivo. La desventaja de esta forma es que primero descarga la rama remota predeterminada y luego cambia — un paso adicional, menos limpio que las dos formas anteriores. Ademas, si la rama objetivo ya esta en uso por otro worktree, se encontrara con un conflicto de ramas:

Como se muestra en la captura, Claude detecta el conflicto de ramas y ofrece dos opciones: volver al directorio principal para operar, o crear una nueva rama de trabajo basada en la rama objetivo. Aunque eventualmente funciona, el proceso no es tan directo como las formas 1 y 2.

Avanzado: encapsular en un comando unico con Makefile

Si frecuentemente necesita crear worktrees desde la rama actual, puede agregar un comando rapido al Makefile en la raiz del proyecto, encadenando la creacion + apertura del editor + inicio de Claude en un pipeline determinista:

# Crear worktree desde la rama actual e iniciar el entorno de desarrollo
# Uso: make worktree name=my-feature
worktree:
	@if [ -z "$(name)" ]; then \
		echo "用法: make worktree name=<worktree-name>"; \
		echo "示例: make worktree name=fix-login-bug"; \
		exit 1; \
	fi
	@echo "→ 从 $$(git branch --show-current) 创建 worktree: $(name)"
	git worktree add -b $(name) .claude/worktrees/$(name) HEAD
	@echo "→ 初始化环境"
	cd .claude/worktrees/$(name) && npm install
	@echo "→ 在 Zed 中打开"
	zed .claude/worktrees/$(name)
	@echo "→ 启动 Claude"
	cd .claude/worktrees/$(name) && claude

Su uso es muy sencillo:

# Crear worktree basado en la rama actual, abrir en Zed e iniciar Claude
make worktree name=fix-login-bug

# Abrir varias tareas en paralelo
make worktree name=feature-search
make worktree name=refactor-api

En comparacion con escribir manualmente multiples comandos Git/cd/claude, make worktree name=xxx requiere solo una linea, y el flujo ejecutado es exactamente el mismo cada vez — no olvidara ningun paso ni escribira mal una ruta. Es importante tener en cuenta que, como el Makefile utiliza git worktree add nativo, el Hook WorktreeCreate de Claude Code no se activara (dicho Hook solo se activa al usar claude -w o al crear worktree dentro de la conversacion). Por lo tanto, los pasos de inicializacion del entorno (instalacion de dependencias, copia de .env, etc.) deben escribirse directamente en el Makefile, como se muestra en el ejemplo anterior con npm install.

Paso 2: Inicializar el entorno

Una vez creado el Worktree, lo primero es inicializar el entorno de desarrollo. Cada nuevo worktree es un directorio independiente; node_modules, entornos virtuales, archivos .env, etc., no se transfieren automaticamente.

Claude Code proporciona el Hook WorktreeCreate para automatizar la configuracion del entorno:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "command": "npm install && cp ../.env .env"
      }
    ]
  }
}

De esta forma, cada vez que se crea un worktree, las dependencias se instalan automaticamente y el archivo de variables de entorno se copia automaticamente. Pasos de inicializacion comunes:

Si no ha configurado el Hook, tambien puede ejecutar /init al inicio de cada sesion de worktree para asegurar que Claude comprenda correctamente el contexto del directorio de trabajo actual, releyendo la estructura del proyecto y la configuracion de CLAUDE.md.

Paso 3: Commit y fusion

Una vez que el entorno esta listo y el desarrollo completado, el siguiente paso es fusionar los cambios de vuelta a la rama objetivo.

Fusionar de vuelta a la rama main

El caso mas comun — el worktree se creo desde origin/main y los cambios deben fusionarse de vuelta a main. En la sesion de Claude del worktree, simplemente diga:

> 提交所有改动，推送到远端，然后创建一个 PR 到 main

Claude completara automaticamente todo el flujo de commit, push y gh pr create.

Fusionar de vuelta a una rama feature

Si esta desarrollando en la rama feature-x y los cambios del worktree deben fusionarse de vuelta a feature-x en lugar de main:

> 提交改动并推送，然后创建一个 PR 合并到 feature-x 分支

Claude ejecutara gh pr create --base feature-x, creando un PR directamente hacia la rama feature.

Tambien puede salir de la sesion del worktree (eligiendo conservar el worktree) y volver al directorio principal para iniciar Claude:

> 把 worktree-my-task 分支的改动合并到当前分支

Si hay algunos commits en el worktree que no desea, puede hacer cherry-pick selectivamente:

> 帮我查看 worktree-my-task 分支的 commit 历史，然后把其中关于认证模块的那几个 commit cherry-pick 到当前分支

Nota: Todos los worktrees comparten la misma base de datos .git. Los commits creados en un worktree son inmediatamente visibles en el directorio principal, sin necesidad de operaciones adicionales de push/pull.

Paso 4: Salir y limpiar

Una vez completada la fusion del codigo, puede salir de la sesion del worktree.

Al salir de la sesion del worktree, Claude procesara automaticamente segun la situacion:

Los worktrees conservados permanecen disponibles para que pueda continuar trabajando mas adelante.

Tambien puede configurar el Hook WorktreeRemove para automatizar la limpieza:

{
  "hooks": {
    "WorktreeRemove": [
      {
        "command": "echo 'Worktree cleaned up'"
      }
    ]
  }
}

Comandos de gestion manual

Si necesita gestionar worktrees manualmente, puede usar los comandos estandar de Git:

# Listar todos los worktrees
git worktree list

# Eliminar manualmente un worktree
git worktree remove .claude/worktrees/feature-auth

# Limpiar referencias de worktrees obsoletos
git worktree prune

Nota: No elimine directamente el directorio del worktree con rm -rf. La forma correcta es usar git worktree remove, o si ya lo elimino por error, ejecute git worktree prune para limpiar las referencias residuales.

Patrones de desarrollo paralelo

Una vez dominado el flujo de trabajo basico, veamos como aprovechar worktree para el desarrollo paralelo.

Multiples terminales en paralelo

El uso mas comun es ejecutar simultaneamente en multiples pestanas de terminal:

# Terminal 1: Manejar la funcionalidad de autenticacion de usuarios
claude -w feature-auth

# Terminal 2: Corregir bug de pagos
claude -w bugfix-payment

# Terminal 3: Refactorizar modulo de API
claude -w refactor-api

Cada instancia de Claude trabaja en su propio worktree, y las modificaciones no se afectan entre si. Puede:

• En una terminal, dejar que Claude desarrolle una nueva funcionalidad
• En otra terminal, dejar que Claude corrija un bug
• En una tercera terminal, continuar con su propia revision de codigo

Implementacion competitiva

Un uso muy eficiente es que multiples Agents implementen independientemente la misma funcionalidad:

# Tres terminales ejecutandose por separado
claude -w feature-search-v1
claude -w feature-search-v2
claude -w feature-search-v3

Proporcioneles los mismos requisitos y deje que cada uno implemente su version. Al final, compare las tres soluciones y fusione la mejor. Esto aprovecha la naturaleza no determinista de los LLM — la misma entrada puede producir diferentes salidas, y a veces la segunda version resulta ser mejor.

La exploracion de diseno de UI tambien es muy adecuada para este patron. Suponga que desea redisenar la interfaz de su aplicacion pero no esta seguro de que estilo es mejor:

# Dejar que tres Agents implementen diferentes estilos
claude -w ui-minimal    # estilo minimalista
claude -w ui-colorful   # colores vibrantes
claude -w ui-glassmorphism  # estilo glassmorphism

Una vez completados, ejecute los servidores de desarrollo de las tres versiones simultaneamente (en diferentes puertos), compare los resultados lado a lado y fusione la solucion preferida a la rama principal — mucho mas eficiente que el flujo tradicional de "hacer una version, ver el resultado, no queda bien, volver a cambiar".

Aislamiento de Subagent

Worktree no solo es util para la instancia principal de Claude, sino tambien para los Subagent. En el frontmatter de un Subagent personalizado, agregue isolation: worktree:

---
name: code-migrator
description: Handles large-scale code migrations. Use for batch refactoring.
tools: Read, Write, Edit, Bash, Grep, Glob
isolation: worktree
---

You are a code migration specialist...

Tambien puede indicarlo directamente a Claude en la conversacion:

> 使用 worktree 来隔离你的 agents
> use worktrees for your agents

Cuando un Subagent esta configurado con aislamiento worktree:

Agent principal (directorio principal)
│
├── Inicia Migration Agent 1 ──→ worktree-migration-1/
│   └── Procesa directorio src/auth/
│
├── Inicia Migration Agent 2 ──→ worktree-migration-2/
│   └── Procesa directorio src/api/
│
└── Inicia Migration Agent 3 ──→ worktree-migration-3/
    └── Procesa directorio src/utils/

Cada Subagent trabaja de forma independiente en su propio worktree, sin interferir entre si. Al finalizar, el worktree se limpia automaticamente (si no hay cambios sin confirmar).

Combinacion con Tmux e IDE

Con el parametro --tmux, puede iniciar automaticamente en una nueva sesion de Tmux; incluso si cierra la terminal, Claude seguira ejecutandose en segundo plano:

claude -w feature-auth --tmux

Si utiliza VS Code o Cursor, el panel de control de codigo fuente reconocera automaticamente todos los worktrees — el repositorio principal se muestra como un repo, y cada worktree aparece como un repo independiente, permitiendo cambiar, confirmar y enviar directamente desde el IDE. Los Worktrees tambien se pueden combinar con el ciclo Ralph; cada ciclo Ralph se ejecuta en su propio worktree, de modo que incluso si el ciclo falla, no afectara la rama principal.

Consideraciones y mejores practicas

Errores comunes

1. Confundir el origen de la rama: Los worktrees creados con -w hacen checkout desde la rama remota predeterminada, no desde la rama en la que se encuentra actualmente. Si ejecuta claude -w my-task estando en la rama feature-x, el codigo del nuevo worktree proviene de origin/main y no incluira los cambios de feature-x. Para trabajar desde la rama actual, consulte Crear desde la rama actual o una rama especifica.
2. Los cambios no confirmados no se transfieren: Al crear un worktree, las modificaciones no preparadas o no confirmadas del directorio principal no apareceran en el nuevo worktree. Los Worktrees se crean unicamente basandose en el historial de commits, asi que asegurese de que los cambios importantes esten confirmados.
3. La misma rama no puede ser utilizada por multiples Worktrees: Git no permite que dos worktrees tengan la misma rama en checkout simultaneamente. Si ya esta en la rama feature-x en el directorio principal, intentar hacer checkout de feature-x en un worktree generara un error. Cada worktree debe estar en una rama diferente.
4. El entorno necesita reinicializarse: Cada nuevo worktree no incluye dependencias de ejecucion como node_modules; se recomienda configurar el Hook WorktreeCreate para automatizar esto (consulte Paso 2: Inicializar el entorno).

Recomendaciones de uso

No se exceda. Aunque tecnicamente puede abrir muchos worktrees, cada instancia de Claude consume cuota de API, demasiadas tareas en paralelo son dificiles de rastrear, y los conflictos al momento de fusionar se vuelven mas complejos.

Convencion de nombres: Adopte buenos habitos de nomenclatura para facilitar la gestion posterior:

# Buenos nombres
claude -w feature-user-auth
claude -w bugfix-payment-123
claude -w refactor-api-v2

# Malos nombres
claude -w test
claude -w temp
claude -w 1

Control de versiones no-Git

Si utiliza SVN, Perforce o Mercurial, puede lograr un efecto de aislamiento similar configurando los Hooks WorktreeCreate y WorktreeRemove. Al configurar estos Hooks, usar --worktree invocara sus comandos personalizados en lugar del comportamiento predeterminado de Git.

Reflexiones finales

Worktree es una funcionalidad que el equipo de Claude Code utiliza todos los dias; Boris Cherny la denomina "el consejo de productividad numero uno". El valor principal es simple: permitir que multiples Agents trabajen en paralelo sin interferir entre si.

Comenzar es sencillo, solo necesita:

claude -w your-task-name

Lecturas relacionadas:

• Guia completa de Claude Subagent — Comprender la sinergia entre Subagent y Worktree
• Analisis profundo de Ralph Wiggum — Otro metodo para mejorar la eficiencia de la programacion con IA
• Analisis completo de la arquitectura de Claude — Comprender la posicion de Worktree en la arquitectura general

Referencias:

• Documentacion oficial de Claude Code - Common Workflows
• Anuncio de Worktree de Boris Cherny
• Documentacion oficial de Git Worktree
• incident.io - Shipping faster with Claude Code and Git Worktrees
• Dev.to - Git worktree + Claude Code: My Secret to 10x Developer Productivity

Tutoriales en video:

• I'm using claude --worktree for everything now — Demostracion practica del flujo de trabajo completo con worktree
• Git Worktrees: The secret sauce to Claude Code! — Metodo de creacion manual de worktree
• Native Worktrees Just Killed Traditional Claude Code Workflows — Explicacion detallada de la funcionalidad nativa de worktree
• Claude Code Worktrees in 7 Minutes — Tutorial rapido que incluye el uso con Subagent
• Stop Using Claude Code on One Branch — Ventajas del desarrollo paralelo con multiples worktrees