Worktree de git en Claude Code

Un worktree de git es un segundo (o tercer, o décimo) directorio de trabajo conectado al mismo repositorio, cada uno con su propia rama y sus propios archivos en disco. En Claude Code se usa para lanzar varias sesiones del agente a la vez sobre el mismo proyecto, cada una aislada en su carpeta, de modo que una puede refactorizar el backend mientras otra arregla un bug en el frontend sin que sus ediciones colisionen.

Cómo funciona

Git separa dos cosas: la base de datos del repositorio (la carpeta .git, con commits, objetos y ramas) y el directorio de trabajo, que es lo que ves y editas. Normalmente hay un solo directorio de trabajo. Con git worktree puedes crear varios que comparten la misma base de datos:

git worktree add ../mi-app-auth -b feature/auth
git worktree add ../mi-app-fix-pagos -b fix/pagos
git worktree list

cd ../mi-app-auth && claude

Cada worktree tiene su rama activa, su índice y sus archivos. Un commit hecho en uno es visible al instante desde los demás porque el historial es común, pero los archivos sin confirmar viven solo en su carpeta. Git impide además tener la misma rama abierta en dos worktrees, lo que evita ediciones cruzadas accidentales.

Claude Code trata cada worktree como un proyecto independiente: lee el CLAUDE.md que haya en él, trabaja solo sobre esos archivos y ejecuta comandos en ese directorio. Las versiones recientes de Claude Code incluyen soporte integrado para crear worktrees al lanzar una sesión y para aislar subagentes en su propio worktree; la sintaxis exacta depende de la versión, así que conviene revisar la documentación oficial antes de automatizarlo.

Por qué importa

Un agente de programación tarda minutos en completar una tarea larga. Si solo tienes un directorio, estás bloqueado esperando o, peor, abres una segunda sesión en la misma carpeta y las dos editan los mismos archivos a la vez. Los worktrees convierten esa espera en paralelismo real:

• Aislamiento: cada sesión ve un estado coherente del código, sin cambios a medias de otra.
• Revisión limpia: cada tarea termina en su rama, lista para un diff o un pull request independiente.
• Descarte barato: si un intento sale mal, borras el worktree y la rama sin tocar tu trabajo principal.
• Comparar enfoques: puedes pedir a dos sesiones que resuelvan el mismo problema de forma distinta y quedarte con la mejor.

Es la pieza que permite pasar de usar Claude Code como asistente a orquestar varias tareas a la vez. Si quieres aprender a orquestar Claude Code en proyectos reales, este patrón es de lo primero que conviene dominar.

Ejemplo práctico

Tienes un monorepo y tres tareas: migrar la autenticación, corregir un cálculo de impuestos y subir la cobertura de tests. Creas tres worktrees, abres una terminal en cada uno y lanzas Claude Code con la tarea correspondiente. Mientras trabajan, revisas lo que van produciendo. Al terminar, haces merge de las ramas que funcionan y eliminas los worktrees con git worktree remove ../mi-app-auth.

Errores comunes

• Olvidar las dependencias: un worktree nuevo solo contiene archivos versionados. node_modules, entornos virtuales o el .env no se copian; hay que instalarlos o copiarlos en cada uno.
• Conflictos de puertos: si dos sesiones arrancan el servidor de desarrollo, ambas intentarán usar el mismo puerto.
• Confundirlo con un clon: un clon duplica todo el repositorio; un worktree comparte el historial y ocupa mucho menos.
• No limpiar: borrar la carpeta a mano deja referencias huérfanas; usa git worktree remove o git worktree prune.
• Paralelizar tareas acopladas: si dos tareas tocan los mismos archivos, el conflicto solo se aplaza hasta el merge.