≡En resumen
- Cada worktree tiene su propia copia de los archivos y su propia rama, pero comparte el directorio .git, el historial y los remotos.
- Una misma rama no puede estar abierta en dos worktrees a la vez.
- Claude Code crea y limpia worktrees por ti con --worktree y puede aislar a cada subagente en la suya.
- Una worktree nueva es un checkout limpio: hay que instalar dependencias y copiar los archivos ignorados, como .env.
- Son la forma más simple de que varios agentes trabajen a la vez en el mismo repositorio sin pisarse.
01 ¿Qué es un git worktree?
Normalmente un repositorio de git tiene un único directorio de trabajo: si estás en la rama feature-pagos y te piden arreglar un error urgente en main, tienes que guardar tus cambios con stash o en un commit a medias, cambiar de rama y volver después. Un worktree elimina ese baile: crea una segunda carpeta enlazada al mismo repositorio, con otra rama, y puedes trabajar en las dos a la vez.
A diferencia de clonar el repositorio dos veces, los worktrees comparten el mismo directorio .git: un commit hecho en uno se ve al instante desde el otro, no se duplica el historial y no hay que sincronizar remotos.
02 Comandos básicos de git worktree
| Comando | Qué hace |
|---|---|
| git worktree add ../carpeta -b rama-nueva | Crea una worktree en una rama nueva |
| git worktree add ../carpeta rama-existente | Crea una worktree a partir de una rama que ya existe |
| git worktree list | Lista todas las worktrees del repositorio y su rama |
| git worktree remove ../carpeta | Elimina la worktree (con --force si tiene cambios sin confirmar) |
| git worktree lock / unlock | Impide o vuelve a permitir que se elimine una worktree |
| git worktree prune | Limpia los registros de worktrees cuya carpeta ya no existe |
03 Por qué los worktrees importan con agentes de IA
Un agente de programación como Claude Code edita archivos, ejecuta tests y hace commits. Si lanzas dos sesiones sobre la misma carpeta, una puede romper lo que hace la otra: ediciones simultáneas del mismo archivo, tests que fallan por cambios ajenos o commits que mezclan dos tareas. Con una worktree por sesión, cada agente tiene su copia aislada y sus cambios solo se juntan cuando tú fusionas las ramas.
Tareas en paralelo
Una sesión desarrolla una funcionalidad mientras otra corrige un error y una tercera actualiza dependencias.
Comparar enfoques
Pide la misma tarea a dos sesiones con instrucciones distintas y quédate con la mejor solución.
Revisar sin interrumpir
Abre la rama de un pull request en su propia worktree para revisarla sin tocar tu trabajo en curso.
Menos riesgo
Si un agente se equivoca, borras su worktree y tu carpeta principal queda intacta.
04 Cómo usar worktrees en Claude Code
-
1
Arranca en una worktree
Ejecuta claude --worktree feature-auth (o -w). Claude Code crea .claude/worktrees/feature-auth/ en una rama nueva llamada worktree-feature-auth.
-
2
Abre más sesiones
En otra terminal, repite el comando con otro nombre. Si no pones nombre, Claude genera uno aleatorio.
-
3
Prepara el entorno
La worktree es un checkout limpio: instala dependencias y copia los archivos ignorados, o automatízalo con .worktreeinclude.
-
4
Trabaja y haz commit
Claude edita, prueba y confirma cambios en su rama sin tocar la carpeta principal.
-
5
Sal y limpia
Al salir, si la worktree está limpia se elimina con su rama; si tiene cambios, Claude Code te pregunta si quieres conservarla.
También puedes pedirle a Claude en mitad de una sesión que "trabaje en una worktree" y la crea por ti. Por defecto, las worktrees nuevas parten de la rama por defecto del remoto, normalmente main; si quieres que partan de tu trabajo actual, pon worktree.baseRef con el valor head en los ajustes. Con claude --worktree "#1234" se crea una worktree a partir de un pull request concreto.
05 Copiar archivos ignorados con .worktreeinclude
Los archivos que git ignora, como .env o una configuración local, no existen en una worktree nueva, y sin ellos la aplicación no arranca ni pasan los tests. Si creas un archivo .worktreeinclude en la raíz del proyecto, con la misma sintaxis que .gitignore, Claude Code copia a cada worktree nueva los archivos que coinciden con algún patrón y además están ignorados por git.
Un archivo con tres líneas: .env, .env.local y config/secrets.json. Cada worktree que cree Claude Code, ya sea con --worktree, para un subagente o desde la app de escritorio, recibirá una copia de esos archivos. Los archivos versionados nunca se duplican por esta vía.
06 Subagentes aislados en su propia worktree
Los subagentes también pueden trabajar cada uno en su worktree, para que sus ediciones en paralelo no choquen. Basta con pedirle a Claude que use worktrees para sus agentes o, para que sea permanente, añadir isolation: worktree al frontmatter de un subagente personalizado. Cuando el subagente termina sin cambios, su worktree se elimina; si deja cambios, se conserva hasta que una limpieza periódica pueda borrarla sin perder trabajo.
| Elemento | ¿Compartido? |
|---|---|
| Historial y directorio .git | Sí: un commit en una worktree se ve desde las demás |
| Archivos de trabajo y rama | No: cada worktree tiene los suyos |
| Plugins instalados a nivel de proyecto | Sí, se cargan también en las worktrees |
| Permisos aprobados con no volver a preguntar | Sí, se guardan en la configuración local de la carpeta principal |
| Memoria automática de Claude Code | Sí, es una por repositorio |
| Archivos ignorados como .env | No, salvo que los copies con .worktreeinclude |
07 Worktrees en la app de escritorio y sin git
En Claude Desktop, al iniciar una sesión de código puedes marcar la opción de worktree para que trabaje en su propia copia; así se pueden llevar varias sesiones en paralelo desde la misma ventana. Si tu equipo no usa git sino SVN, Perforce o Mercurial, los hooks WorktreeCreate y WorktreeRemove sustituyen la lógica de git por la de tu sistema de control de versiones.
- ✓Usa un nombre descriptivo por tarea para encontrar luego la rama y la sesión.
- ✓Instala dependencias en cada worktree o compártelas con la herramienta de tu ecosistema, si lo permite.
- ✓Revisa git worktree list de vez en cuando y elimina las que ya no uses.
- ✓Si git se niega a borrar una worktree bloqueada, ejecuta git worktree unlock antes de git worktree remove.
- ✓Fusiona las ramas de cada worktree con una revisión, igual que harías con el trabajo de una persona.
08 Un flujo de trabajo de equipo con worktrees
Por la mañana, un desarrollador lanza tres sesiones: claude -w informes-pdf para una funcionalidad nueva, claude -w fix-login para un error reportado por un cliente y claude -w upgrade-deps para actualizar dependencias. Mientras los agentes trabajan, él revisa los planes y responde dudas. Al final del día, cada worktree ha generado su rama, cada rama su pull request y la carpeta principal no se ha tocado.
Es el modo de trabajo que aplicamos en el desarrollo de software SaaS y en el desarrollo de aplicaciones web: paralelizar con agentes sin renunciar a revisar cada cambio.
Si quieres ver más utilidades de la comunidad para orquestar varias sesiones y agentes, échale un vistazo a nuestro índice de herramientas para Claude Code.
Preguntas frecuentes sobre Git worktrees
Es un directorio de trabajo adicional de un mismo repositorio, con su propia rama y sus propios archivos, que comparte el historial y el directorio .git con el original.
Un clon duplica todo el historial y tiene su propio .git, que hay que sincronizar. Las worktrees comparten un único .git, así que ocupan menos y los commits de una se ven al momento desde las demás.
Con git worktree add ../carpeta -b rama-nueva para una rama nueva, o git worktree add ../carpeta rama-existente para una que ya existe. En Claude Code, basta con claude --worktree y un nombre.
Por defecto en .claude/worktrees/nombre/ dentro del repositorio, en una rama llamada worktree-nombre. Conviene añadir .claude/worktrees/ al .gitignore.
Porque es un checkout limpio: faltan las dependencias y los archivos ignorados como .env. Instala las dependencias y usa un archivo .worktreeinclude para que Claude Code copie esos archivos automáticamente.
Con git worktree remove y la ruta, añadiendo --force si tiene cambios sin confirmar. Si está bloqueado, ejecuta antes git worktree unlock. Claude Code elimina por sí mismo las suyas cuando están limpias.
Fuentes consultadas
Sobre el autor
Germán Gutiérrez
Development Manager en appyweb
Dirige el equipo de desarrollo de appyweb: aplicaciones web y móviles, SaaS, integraciones y arquitectura de software.
Ver perfil en LinkedIn ↗