Ejecutar sesiones de Claude Code una tras otra es un hábito, no un requisito. Cuando tus tareas son genuinamente independientes, no hay razón para que una tenga que esperar a la otra. Los worktrees de Git le dan a cada sesión de Claude su propio directorio extraído en su propia rama, todos extrayendo del mismo almacén de objetos .git. Sin clones duplicados, sin conflictos de archivos, fusión estándar de git cuando termines. Este artículo te guía a través del flujo de trabajo completo: cuándo recurrir a un worktree, cómo configurar uno, qué aislamiento realmente obtienes (y qué no), y cómo limpiar sin perder trabajo que aún no ha sido confirmado.
Cuándo un Worktree Ayuda
No toda tarea justifica uno. Respuesta honesta: los worktrees brillan en una banda bastante específica de situaciones.
Un tutorial de YouTube de bri (junio de 2026) lo explica bien. Usa un worktree cuando tienes dos o más tareas que no comparten los mismos archivos, o cuando una tarea es lo suficientemente arriesgada como para que quieras ver dos enfoques diferentes antes de comprometerte con uno. Si una sola tarea abarca toda la base de código, mantente en una sesión. Lo mismo aplica para trabajo exploratorio donde quieres que el agente se mueva libremente.
El otro buen caso de uso: trabajo especulativo. Inicia tres worktrees, dale a cada uno un prompt ligeramente diferente para el mismo problema, y elige la versión que te gusta. Zylos Research señala que este patrón se ha vuelto común en equipos que ejecutan cuatro o más sesiones de IA concurrentes, precisamente porque estás cubriendo riesgos contra salidas de modelo no determinísticas en lugar de confiar en un único intento.
Por el contrario, si tu proyecto involucra un monorepo grande de TypeScript con PostgreSQL, Redis, múltiples paquetes internos y un frontend Remix, los worktrees por sí solos no resolverán tus problemas de coordinación. Trigger.dev escribió exactamente sobre esto y eventualmente cambió a un enfoque diferente. El aislamiento del sistema de archivos es real. El aislamiento de servicios no es automático.
Crea Extracciones de Tareas Aisladas
Comienza en tu rama base y obtén lo más reciente. Luego agrega .claude/worktrees a tu .gitignore una sola vez:
echo ".claude/worktrees" >> .gitignore
Claude coloca worktrees dentro de tu directorio de repositorio por defecto. Sin esa entrada .gitignore, aparecen como archivos sin seguimiento y saturan tu git status. Agrégalo, confírmalo, olvídalo.
Ahora inicia una sesión por tarea. Abre dos terminales:
claude --worktree feature-payments
``
claude --worktree bugfix-auth
Según la descripción de Dan Does Code, Claude crea el worktree en .claude/worktrees/feature-payments/, verifica una rama nueva y limita la sesión a ese directorio. Tu árbol de trabajo principal permanece intacto en todo momento. También puedes usar la forma de bandera corta claude -w feature-payments si lo prefieres. Salta el nombre por completo y Claude genera uno automáticamente.
Cada sesión ahora opera en aislamiento completo del sistema de archivos. El agente en Terminal 1 no puede tocar los archivos en los que el agente en Terminal 2 está trabajando, porque están en directorios diferentes en ramas diferentes. Ese es el truco completo. Es separación a nivel de infraestructura, no lógica de coordinación entre agentes. (La guía de subagentes de Claude Code cubre el lado de la orquestación si eso es lo que buscas en su lugar.)
Dándole a Cada Sesión su Tarea
Una vez que ambas sesiones estén ejecutándose, dale a cada una sus instrucciones. Trata cada instancia de Claude como un contexto nuevo. Sé específico sobre el alcance. Si Terminal 1 está construyendo una función de pagos, dile qué archivos tocar y cuáles dejar solos. Lo mismo para Terminal 2.
Cuando una sesión termina, pídele a Claude que envíe la rama y abra una solicitud de extracción antes de cerrar la terminal. De esa forma, el trabajo está seguro fuera de tu máquina local y listo para revisar.
Gestionar dependencias, puertos y configuración local
Aquí es donde las cosas se ponen delicadas. El aislamiento del sistema de archivos es automático. Todo lo demás requiere un poco de configuración manual.
Puertos. Si ambos worktrees inician un servidor de desarrollo, colisionarán en el mismo puerto de forma predeterminada. La solución es darle a cada worktree su propio archivo .env con una asignación de puerto diferente. Algo como PORT=3001 en uno y PORT=3002 en el otro. O pasa el override en línea al iniciar. Cualquiera funciona.
Bases de datos. SQLite es fácil: apunta el .env de cada worktree a una ruta de archivo diferente. PostgreSQL o MySQL requieren más consideración. Necesitas una instancia de base de datos separada por worktree, o como mínimo un esquema o base de datos separado dentro de la misma instancia. Configura la cadena de conexión mediante variables de entorno en el .env de cada worktree. No compartas una base de datos entre dos agentes que escriben migraciones simultáneamente. Eso es pedir corrupción o condiciones de carrera.
Archivos de configuración local. Si tu proyecto usa un archivo de configuración local que no está comprometido (cosas como .env.local, config/local.yml), necesitarás crear uno por worktree. No heredan del árbol de trabajo principal automáticamente.
La guía de MindStudio sobre agentes de codificación de IA paralela cubre estos patrones de aislamiento con más detalle. La versión corta: los worktrees te dan aislamiento de rama y directorio por diseño. El aislamiento de base de datos y puerto requiere que lo configures explícitamente, de antemano.
Una cosa más que vale la pena señalar aquí. Si trabajas en un proyecto con configuración de servicio local costosa o complicada y ejecutas múltiples worktrees, considera si el costo de configuración vale la aceleración paralela. Para una biblioteca o herramienta CLI, absolutamente. Para un monorepo full-stack con seis servicios, quizá menos. Si quieres ayuda para definir el alcance, un desarrollador de Claude Code puede evaluar si los worktrees u otra estrategia paralela se ajustan a tu stack.
Revisar e integrar ambas ramas
Ambos agentes han terminado. Ambas ramas están enviadas. Ahora revisas.
El flujo de trabajo aquí es git estándar. La configuración paralela no cambia el proceso de fusión en absoluto. Una secuencia numerada para un repositorio típico de dos tareas:
- Cambia a
mainy obtén los últimos cambios. - Revisa la primera rama.
git diff main..feature-paymentste da una imagen completa de qué cambió. - Si estás satisfecho con ella, fusiona o rebase en
main. Resuelve los conflictos con la rama base de la manera habitual. - Obtén
mainde nuevo para conseguir esos cambios. - Revisa la segunda rama.
git diff main..bugfix-auth. - Fusiona. Si los dos agentes tocaron archivos superpuestos (lo que no debería suceder si definiste las tareas correctamente, pero a veces ocurre), resuelve los conflictos aquí.
- Ejecuta tu suite de pruebas contra
mainuna vez que ambas fusiones estén dentro.
La ventaja de revisar secuencialmente como esto, en lugar de fusionar ambas simultáneamente, es que los conflictos de una fusión no se acumulan en la siguiente. Diffs más simples, razonamiento más fácil.
Limpiar sin perder trabajo no comprometido
La limpieza es donde los desarrolladores se ponen nerviosos. ¿Y si hay trabajo en un worktree que nunca fue comprometido?
La respuesta: guárdalo en el stash antes de eliminar el worktree.
Si tienes cambios sin confirmar en un worktree que quieras preservar, navega hacia ese directorio del worktree y ejecuta:
git stash push -m "wip: payments feature - pre-cleanup"
Ese stash vive en el almacén de objetos .git compartido, lo que significa que es accesible desde tu árbol de trabajo principal o cualquier otro worktree después de que se elimine el worktree original. Una vez que hayas hecho stash, puedes eliminar de forma segura:
git worktree remove .claude/worktrees/feature-payments
Luego, de vuelta en tu árbol de trabajo principal, saca el stash:
git stash pop
Si el experimento falló por completo y no quieres nada de él, simplemente elimina sin hacer stash. git worktree remove con la bandera --force elimina el worktree incluso si tiene cambios sin confirmar. Asegúrate antes de usar --force. No hay ruta de recuperación.
Después de eliminar todos los worktrees, limpia la lista para mantener todo ordenado:
git worktree prune
Eso elimina cualquier referencia administrativa obsoleta de .git/worktrees/.
Recursos Compartidos Que Los Worktrees No Aíslan
Vale la pena ser explícito sobre esto, porque el modelo mental de "aislamiento" puede confundirte.
Lo que los worktrees sí aíslan:
- El directorio de trabajo y todos los archivos en él
- La rama en la que opera cada sesión
- Cambios organizados y sin organizar
Lo que los worktrees no aíslan:
- El almacén de objetos
.git(compartido por diseño) - La memoria automática local de la máquina (la documentación oficial de memoria confirma que los worktrees del mismo repositorio comparten esto)
- Servicios externos: bases de datos, colas, cachés, cualquier dependencia en red
- Credenciales de entorno y claves API a menos que establezca explícitamente valores diferentes por worktree
- Cualquier cosa en el entorno shell a nivel del sistema operativo que ambas sesiones hereden
Esto también importa para la seguridad. Los worktrees no son un límite de inquilino. Si ambas sesiones comparten la misma clave API o credenciales de base de datos, comparten acceso. No trates un worktree como una forma de aislar una sesión de Claude de la configuración local sensible. No es así.
Para orquestar múltiples agentes en un flujo de trabajo más amplio en lugar de solo aislamiento del sistema de archivos, el artículo de superpoderes de Claude Code profundiza en los patrones más amplios.
FAQ
¿Funciona `claude --worktree` igual que ejecutar `git worktree add` manualmente?
Funcionalmente similar pero no idéntico. claude --worktree hace el git worktree add, crea la rama y delimita la sesión de Claude a ese directorio en un paso. Si ejecutas git worktree add manualmente y luego inicias Claude dentro del directorio resultante, obtienes el mismo resultado del sistema de archivos pero sin el alcance integrado de Claude. La bandera --worktree es el camino más rápido para el caso común.
¿Puedo ejecutar más de dos worktrees a la vez?
Sí. No hay límite duro impuesto por git o Claude Code en la cantidad de worktrees. El límite práctico es la RAM y CPU de tu máquina. Cada sesión de Claude es un proceso separado con su propio contexto. Tres o cuatro sesiones concurrentes en una máquina de desarrollo moderna está bien. Si tienes más que eso, probablemente estés alcanzando limitaciones de recursos antes de llegar a ninguna limitación de git.
¿Qué sucede con la rama de un worktree si lo elimino?
La rama sobrevive. git worktree remove elimina el directorio de trabajo y la referencia administrativa en .git/worktrees/. La rama en sí permanece y es accesible desde tu árbol de trabajo principal o cualquier otro worktree. Eliminas la rama por separado con git branch -d nombre-rama cuando ya no la necesites.
¿Los worktrees afectan cómo Claude lee o escribe el archivo `CLAUDE.md` de memoria del proyecto?
Los worktrees en el mismo repositorio comparten memoria automática local según la documentación oficial de memoria. Si tienes un archivo CLAUDE.md confirmado en el repositorio, cada worktree lo lee desde su propia copia extraída. Los cambios que un agente hace a CLAUDE.md en su worktree permanecen aislados en esa rama hasta que se fusionan. Pero la capa local de la máquina se comparte, así que las instrucciones escritas allí por una sesión son visibles para otra.
¿Hay un costo de rendimiento al ejecutar worktrees versus clones separados?
Los worktrees son más económicos que los clones. Comparten el almacén de objetos .git, así que no hay duplicación de todo el historial del repositorio en disco. El costo principal es el directorio de trabajo en sí, que es una extracción completa de todos los archivos rastreados en el estado actual de la rama. Para repositorios grandes con activos binarios o archivos generados, ese tamaño de extracción puede acumularse. Pero las operaciones de git (fetch, log, diff) se ejecutan todas contra un único almacén de objetos, así que son rápidas.
La razón más clara para preferir worktrees sobre clones separados: los stashes y referencias creados en un worktree son inmediatamente accesibles en todos los demás lugares del mismo repositorio. Ese estado compartido es exactamente lo que hace que funcione el flujo de limpieza anterior.