Git Worktrees con Claude Code: ejecuta sesiones paralelas sin conflictos

- Los números de versión, el comportamiento de las flags y la tabla de comparación de worktrees frente a agentes de abajo se contrastaron con la documentación oficial en vivo el 2026-08-20; el comportamiento de worktree de Claude Code ha tenido varios cambios este año, así que verifícalo antes de depender de cualquier cosa de aquí.

El problema: por qué un solo directorio de trabajo rompe las sesiones paralelas de Claude Code

Ejecuta dos sesiones de Claude Code en la misma carpeta y tarde o temprano chocas con el mismo muro: la sesión A está a mitad de una edición en un archivo, la sesión B toca el mismo archivo, y ahora estás resolviendo un conflicto que ninguna de las dos sesiones causó a propósito. Tres modos de fallo concretos aparecen rápido:

• Las ediciones de archivos chocan - dos sesiones escriben en el mismo archivo a la vez, y una sobrescribe el trabajo de la otra.
• Las pruebas fallan por razones que no tienen nada que ver con tu cambio - una instalación de dependencias, una migración a medias o un archivo perdido que dejó la tarea de la otra sesión.
• Confusión de ramas y contexto - pierdes la pista de qué sesión tocó qué, y git status deja de significar algo útil.

La propia documentación de Claude Code plantea la solución de la misma manera: ejecuta cada sesión en su propio worktree para que "una sesión pueda construir una función mientras una segunda corrige un bug", sin que ninguna toque los archivos de la otra. Si Claude Code en general es nuevo para ti, empieza por qué es Claude Code primero; esta guía da por hecho que ya lo usas a diario y acabas de chocar exactamente con este muro.

Inicio rápido: arranca Claude en un worktree

Pasa --worktree (o la flag corta -w) con un nombre para crear un worktree aislado e iniciar una sesión dentro de él en un solo paso:

claude --worktree feature-auth

Por defecto, Claude Code crea el worktree en .claude/worktrees/feature-auth/, en la raíz de tu repositorio, en una rama nueva llamada worktree-feature-auth. Abre una segunda terminal, ejecuta el mismo comando con un nombre distinto y tienes una segunda sesión totalmente aislada que apunta al mismo historial del repositorio:

claude --worktree fix-checkout-race

Omite el nombre por completo y Claude genera uno por ti - algo como bright-running-fox - que está bien para una sesión desechable, pero hace más difícil distinguir tres terminales después, así que ponle nombre a todo lo que planees conservar.

Dos cosas para configurar una vez y olvidar:

• Agrega .claude/worktrees/ a tu .gitignore, para que el contenido de los worktrees no aparezca como archivos sin seguimiento en tu checkout principal.
• Las ejecuciones interactivas requieren confianza en el workspace: si nunca antes ejecutaste Claude en este repositorio, ejecuta claude una vez en el checkout principal para aceptar el diálogo de confianza, o --worktree sale con un error que te lo indica. Las ejecuciones no interactivas con -p se saltan esta comprobación por completo, así que claude -p --worktree <name> avanza sin preguntar - útil para ejecuciones en script o al estilo CI.

Un worktree es un checkout nuevo, no un clon con tu configuración local incorporada - instala las dependencias (o pídeselo a Claude) antes de empezar a trabajar. La siguiente sección explica cómo llevar tu .env contigo automáticamente.

Worktrees vs. subagents vs. agent view vs. agent teams: ¿cuál quieres de verdad?

Los worktrees resuelven exactamente un problema: sesiones paralelas que tocan los mismos archivos. No deciden quién coordina el trabajo ni si los trabajadores hablan entre sí - para eso, la propia documentación de Claude Code presenta un marco de decisión genuinamente útil en su página de comparación de agentes (consultada el 2026-08-20), construido en torno a tres preguntas: quién coordina el trabajo, si los trabajadores necesitan hablar entre sí y si las tareas tocan los mismos archivos. Los worktrees solo responden a la última.

En la práctica los combinas: el agent view mueve automáticamente cada sesión despachada a su propio worktree, y un subagent que crees también puede tener uno (siguiente sección). Los agent teams son la única excepción que vale la pena señalar - los compañeros de equipo no están aislados en worktrees por defecto, así que particionas la propiedad de los archivos a mano. Si ya estás coordinando varios subagents en una sesión, consulta orquestar subagents en Claude Code; para la configuración multisesión más nueva y aún experimental, consulta los agent teams de Claude Code.

Lleva tu entorno y tus secretos a cada nuevo worktree (.worktreeinclude)

Un worktree es un checkout nuevo: los archivos ignorados por git, como .env o .env.local, simplemente no están ahí, porque git nunca los rastreó. Agrega un archivo .worktreeinclude en la raíz de tu proyecto para copiarlos automáticamente cada vez que Claude cree un worktree. Usa la sintaxis de .gitignore y solo copia archivos que a la vez coinciden con un patrón y ya están ignorados por git - los archivos rastreados nunca se duplican:

.env
.env.local
config/secrets.json

Esto aplica a cada worktree que Claude Code crea mediante git: sesiones que inicias con --worktree, worktrees de subagent (siguiente sección) y sesiones paralelas en la app de escritorio. Una excepción que conviene conocer: si reemplazas la creación de worktree por un hook WorktreeCreate para un VCS que no es git, .worktreeinclude se omite por completo, y copias los archivos dentro del script del hook - un caso límite de baja prioridad, a menos que uses SVN o Perforce.

Un flujo real: 3 funciones en paralelo en 3 worktrees

Aquí está la parte que la mayoría de las guías se salta o finge: qué pasa de verdad cuando ejecutas tres sesiones de Claude Code a la vez, usando el toolchain nativo en lugar del git worktree add crudo. Ejecuté exactamente esta configuración - tres terminales, tres worktrees, valores de PORT distintos en cada uno - antes de escribir esta sección, así que los pasos de abajo son lo que de verdad pasó, no una hipótesis.

Digamos que estás trabajando en un rediseño de la página de precios, en la corrección de una condición de carrera en el checkout y en una refactorización del cliente de API al mismo tiempo. Tres terminales (o tres paneles de tmux), tres comandos:

claude --worktree pricing-page
claude --worktree fix-checkout-race
claude --worktree refactor-api-client

Cada uno aterriza en su propio directorio .claude/worktrees/<name>/, en su propia rama worktree-<name>, compartiendo el mismo historial del repositorio. Pasos numerados para el bucle completo:

1. Configura el entorno de cada worktree. Si tienes un archivo .worktreeinclude (sección anterior), tu .env ya está copiado. Dale a cada worktree su propio override de PORT en ese .env - PORT=3001 para pricing-page, 3002 para fix-checkout-race, 3003 para refactor-api-client - para que tres servidores de desarrollo corran a la vez sin pelear por el mismo puerto.
2. Nombra las pestañas de la terminal o los paneles de tmux para que coincidan con el nombre del worktree. Tres terminales sin etiqueta, todas mostrando la salida de "claude", es como pierdes la pista de cuál sesión es cuál para la segunda hora.
3. Deja que cada sesión trabaje de forma independiente. Dale a cada una su propia instrucción acotada y déjala correr; no estás vigilando las tres a la vez.
4. Revisa el estado de las tres desde un solo lugar. Abre claude agents para una vista de las sesiones despachadas, o ejecuta /tasks dentro de cualquier sesión para ver qué corre en segundo plano - no necesitas ir alternando entre las tres terminales solo para revisar el progreso.
5. Haz el merge del más limpio primero. El worktree que termine más limpio (pruebas en verde, sin ediciones a medias) se fusiona y se limpia primero - no dejes que una sesión lenta bloquee las dos que ya están listas.
6. Conserva el que está en progreso al salir. Si sales de una sesión nombrada con trabajo sin commitear, Claude te pregunta si quieres conservar o eliminar el worktree; consérvalo, y estará esperando justo donde lo dejaste la próxima vez.

Lo que de verdad se rompió la primera vez que lo intenté sin aislar los puertos: dos de los tres servidores de desarrollo se negaron a arrancar porque peleaban por localhost:3000, y perdí veinte minutos suponiendo que era un bug de código antes de darme cuenta de que era una colisión de puertos. Esa es toda la razón por la que existe la siguiente sección.

Un detalle más del toolchain nativo que vale la pena conocer aquí: a mitad de la sesión, también puedes pedirle a Claude que "trabaje en un worktree" en lugar de iniciar uno desde la línea de comandos, y crea uno al vuelo con la herramienta EnterWorktree - práctico si decides que necesitas aislamiento a mitad de una conversación en lugar de planearlo desde el principio.

Aísla los subagents en su propio worktree

Los worktrees no son solo para las sesiones que inicias a mano. Un subagent que Claude crea dentro de una sesión también puede tener su propio worktree, para que sus ediciones nunca choquen con las tuyas ni con las de otro subagent. Dos formas de activarlo: pedirle a Claude que "use worktrees para tus agents" a mitad de la sesión, o hacerlo permanente para un subagent personalizado específico agregando isolation: worktree a su frontmatter:

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the
tests and report the results.

Claude Code elimina el worktree temporal de un subagent automáticamente en cuanto termina sin cambios; si dejó cambios, el worktree se queda en disco hasta que el barrido periódico de limpieza pueda eliminarlo sin perder trabajo (siguiente sección). Mientras el subagent está corriendo, Claude Code mantiene un git worktree lock sobre él para que una pasada de limpieza concurrente no lo saque de debajo del agent.

Los worktrees de subagent parten de la misma base que las sesiones --worktree por defecto - la rama por defecto de tu repositorio, a menos que hayas puesto worktree.baseRef en "head" para que los agents aislados puedan operar sobre tu trabajo en progreso. Para el panorama completo de despachar y coordinar varios subagents a la vez, consulta orquestar subagents en Claude Code.

Higiene de puertos, procesos y servidor de desarrollo entre worktrees

Esta es la sección que la mayoría de los competidores se salta o resuelve en una frase suelta, y es la forma más común en que una configuración multi-worktree te desperdicia la tarde: todo parece roto, y en realidad es una colisión de puertos o de base de datos, no un bug de código. Tres cosas de las que cada worktree necesita su propia copia:

Nada de esto es exótico - es la misma higiene que querrías al ejecutar cualesquiera tres servidores de desarrollo locales a la vez. La diferencia con los worktrees es que es fácil olvidarlo, porque el worktree en sí se siente "aislado" aunque el puerto por defecto de tu servidor de desarrollo y tu archivo de base de datos no se aíslen automáticamente junto con él. Configura el override de PORT y la separación de la BD antes de iniciar la sesión, no después de que el segundo servidor de desarrollo se niegue a arrancar.

Limpieza: no dejes que los worktrees se acumulen

Lo que pasa al salir depende de si la sesión tiene nombre y de si el worktree está limpio:

• Sesión sin nombre, worktree limpio: Claude elimina el worktree y su rama automáticamente cuando sales.
• Sesión nombrada, o un worktree con trabajo dentro: Claude te pregunta si conservar o eliminar. Conservar preserva el directorio y la rama para después; eliminar borra el worktree, su rama y todo lo que haya en ellos.
• Ejecuciones no interactivas con -p: no hay ningún aviso de salida, así que nada se limpia automáticamente. El lock que Claude Code pone sobre el worktree al crearlo permanece hasta que el barrido periódico de una sesión posterior lo libera.

Ese barrido periódico elimina los worktrees que Claude creó para subagents y sesiones en segundo plano en cuanto son más viejos que tu ventana de retención cleanupPeriodDays configurada (definida en tus ajustes) - se salta cualquier cosa que aún tenga archivos modificados, archivos sin seguimiento o commits sin subir, y nunca elimina un worktree que creaste directamente con --worktree.

Comandos manuales para cuando quieres el control tú misma:

git worktree list
git worktree remove <path>
git worktree remove --force <path>
git worktree unlock <path>

Si git worktree remove se niega porque el worktree está bloqueado, ejecuta git worktree unlock sobre él primero y luego elimínalo.

Errores comunes

• Arrancar desde dentro de un worktree en vez del checkout principal. Claude Code vuelve a entrar en los worktrees que creó en .claude/worktrees/ aunque arranques desde dentro de uno, pero un worktree que creaste tú misma con el git worktree add crudo (fuera de ese directorio) puede negarse a reanudar si arrancas desde un subdirectorio suyo - arranca esos desde el checkout principal.
• Olvidar poner .claude/worktrees/ en el gitignore. Sáltate esto y el contenido de cada worktree aparece como archivos sin seguimiento que ensucian el git status de tu checkout principal.
• Que te sorprenda el aviso de confirmación de EnterWorktree. A partir de la v2.1.206, cuando Claude intenta entrar en una ruta de worktree fuera de .claude/worktrees/, pide tu aprobación primero, porque ese movimiento entrega acceso de escritura y configuración del proyecto como el CLAUDE.md a esa ubicación. Ni una regla de permiso guardada ni el "no volver a preguntar" lo suprimen - solo el modo bypassPermissions.
• Saltarse el aislamiento de puertos/BD. Ya lo cubrí arriba, pero vale repetirlo: es la mayor fuente de "mis pruebas fallan sin motivo" en una configuración multi-worktree.
• Windows: eliminar un worktree no borra archivos fuera de él - casi siempre. Si una carpeta dentro del worktree es una unión NTFS o un enlace simbólico de directorio, Claude Code borra solo el enlace y conserva la carpeta real a la que apunta. Este comportamiento es vigente en la v2.1.205; verifica que siga siendo correcto si lees esto mucho más tarde, ya que las entrañas del worktree han recibido varias correcciones este año.

¿Editaste el worktree equivocado, o necesitas revertir un cambio que un agent hizo a mitad de la sesión? Consulta cómo deshacer cambios con seguridad en Claude Code - combina de forma natural con ejecutar experimentos dentro de un worktree aislado, para empezar.

Dónde encaja AgentKit (honesto, una sola mención)

Voy a ser directa: los worktrees, .worktreeinclude y EnterWorktree son todos funciones nativas de Claude Code, y ninguno cuesta nada más allá de tu plan actual. AgentKit es un kit de skill/subagent aparte y de pago (agentkit.best, CLI ak) que corre dentro de Claude Code una vez instalado con ak kit init engineer --target claude-code. No cambia cómo funcionan los worktrees - una sesión ejecutando un comando de AgentKit como ak:cook se comporta exactamente igual que cualquier otra sesión de Claude Code dentro de un worktree, checkout aislado incluido.

Una cosa que conviene que compruebes tú misma en lugar de dar por sentada: la documentación de Claude Code confirma que los plugins instalados con alcance de proyecto desde tu checkout principal se cargan automáticamente en cada nuevo worktree de ese repositorio sin reinstalar (a partir de la v2.1.200). Si la ruta de instalación de AgentKit se registra por ese mismo sistema de plugins, o escribe sus archivos de otra manera, no es algo que yo haya confirmado de forma independiente - conviene revisar la propia documentación de AgentKit antes de suponer que tu kit se traslada automáticamente a un worktree nuevo igual que lo haría un plugin de marketplace.

Si estás corriendo el bucle de planear-de-día/ejecutar-de-noche o paralelizando varias funciones y quieres los gates de AgentKit en la mezcla, la reseña completa de AgentKit cubre lo que está de verdad confirmado.

Preguntas frecuentes (FAQ)

¿Necesito worktrees para ejecutar Claude Code en paralelo, o puedo simplemente abrir dos terminales en la misma carpeta?

Dos terminales en la misma carpeta siguen compartiendo un solo directorio de trabajo, así que ambas sesiones editan los mismos archivos y obtienes las colisiones que describe esta guía. Los worktrees le dan a cada sesión su propio checkout del mismo historial del repositorio, así que dos o tres sesiones pueden correr de verdad en paralelo sin tocar los archivos de las demás.

¿La app de escritorio crea worktrees automáticamente?

Sí. En la app de escritorio de Claude Code, cada nueva sesión paralela obtiene su propio worktree automáticamente, sin que tú misma pases --worktree.

¿Pueden dos sesiones de Claude compartir un worktree?

No de forma segura para trabajo paralelo - un worktree está pensado para el checkout aislado de una sola sesión a la vez. Si quieres que dos sesiones vean el estado de la otra o se pasen información, usa mensajería entre sesiones o revisa /tasks y claude agents, no un worktree compartido.

¿Qué pasa con mi .env en un worktree nuevo?

Nada - un worktree es un checkout nuevo, así que los archivos ignorados por git como el .env no se copian por defecto. Agrega un archivo .worktreeinclude (sintaxis de gitignore) en la raíz de tu proyecto y Claude Code copia los archivos ignorados por git que coincidan a cada worktree nuevo automáticamente.

¿Cómo evito que los worktrees se acumulen en el disco?

Las sesiones nombradas y los worktrees con trabajo sin commitear te preguntan si conservar o eliminar al salir; las sesiones limpias y sin nombre se limpian solas. Un barrido periódico también elimina worktrees antiguos de subagent y de sesión en segundo plano según tu ajuste cleanupPeriodDays. Para control manual, ejecuta git worktree list y git worktree remove [--force].

¿Los worktrees funcionan con SVN/Perforce/repositorios que no son git?

No con el flujo por defecto - el aislamiento de worktree usa git por defecto. Para SVN, Perforce, Mercurial u otro VCS, configuras hooks WorktreeCreate/WorktreeRemove para reemplazar la lógica de git con la tuya; ten en cuenta que .worktreeinclude no se procesa en ese camino, así que copias los archivos de configuración dentro del script del hook.

Conclusión

Los worktrees resuelven exactamente un problema bien: sesiones paralelas de Claude Code que no se pisan los archivos entre sí. No coordinan el trabajo por sí solos - combínalos con subagents, agent view o agent teams para esa mitad del cuadro, usando el marco de decisión de arriba en vez de adivinar. Empieza con un worktree extra para tu próxima tarea paralela antes de escalar a tres funciones en paralelo; acierta con .worktreeinclude y el aislamiento de puertos pronto, y la limpieza se resuelve casi sola.