Worktrees de Claude Code: sesiones paralelas sin conflictos
Un comando le da a cada sesión de Claude Code su propia copia completa de tu repo. Aprende claude --worktree, la estructura de .claude/worktrees, el aislamiento por worktree de los subagentes, la limpieza al salir y dónde sigue ganando el git worktree add manual.
TL;DR
- claude --worktree (forma corta -w) arranca tu sesión dentro de una copia nueva del repo en .claude/worktrees/<name>, con checkout en una rama llamada worktree-<name>.
- Lanza más sesiones en otras terminales para trabajar en paralelo — cada sesión edita su propio directorio mientras comparte el mismo historial de Git y el mismo remoto.
- Los subagentes también tienen worktrees: pídelo en lenguaje natural o añade isolation: worktree en el frontmatter de un .claude/agents/*.md para hacerlo permanente.
- Al salir, los worktrees sin nombre y limpios se eliminan automáticamente y el trabajo en curso pregunta si conservarlo o eliminarlo; fusiona los resultados con un git merge normal de worktree-<name>.
Claude Code Worktrees in 7 Minutes
Canal: Developers Digest7:10
I'm using claude --worktree for everything now
Canal: Matt Pocock7:57
Worktrees — official documentation
Documentación oficial: code.claude.com/docs
Cada flag, ruta y comportamiento de limpieza de esta página está verificado contra la documentación oficial de worktrees; los videos de arriba son la fuente visual y de hechos, incluido el aviso de conservar o eliminar al salir y la trampa del push a main.
Las capturas se atribuyen a sus creadores con enlaces profundos a los minutos exactos. No se usan fotogramas con caras.
Usa los worktrees de Claude Code paso a paso
Parte 1 — Tu primera sesión aislada
- 1
Prepara un repo Git con al menos un commit
Los worktrees se ramifican de un historial existente, así que la función necesita un repositorio Git real. En una carpeta nueva ejecuta git init, crea un archivo (la demo solo ejecuta touch index.html) y haz un commit. Si te lo saltas, Claude Code no tendrá nada de donde ramificarse.
git init más touch index.html — un solo commit es todo lo que la función de worktrees necesita antes de que claude --worktree funcione.Ver en 1:06 - 2
Sabe qué es un worktree en realidad
Un worktree de Git es un segundo directorio de trabajo con sus propios archivos y su propia rama en checkout que comparte el historial y el remoto del repositorio. A diferencia de cambiar de rama, aquí nada se guarda aparte: el checkout principal y cada worktree siguen usables a la vez, exactamente lo que necesitan los agentes paralelos.
Un repositorio, muchas carpetas de trabajo: ../main, ../feature1 y ../feature2 están a la vez sobre su propia rama.Ver en 0:30 - 3
Lanza Claude Code con --worktree
Desde dentro del repo ejecuta claude --worktree (o la forma corta claude -w). Claude Code crea .claude/worktrees/<name>, genera un nombre como bright-tumbling-rabbit si no pasas uno y mete la sesión directamente en esa copia. En la app de escritorio eliges la opción de worktree al iniciar la sesión.
El banner de bienvenida muestra que el directorio de trabajo de la sesión ya está dentro de .claude/worktrees — todo lo que venga ocurre en la copia.Ver en 1:22 - 4
Abre una segunda sesión para tu segunda tarea
Ejecuta claude --worktree de nuevo en otra terminal. Sin nombre obtienes otro worktree independiente; pasa el mismo nombre dos veces para reabrir el mismo. Dos agentes ya pueden editar el mismo proyecto a la vez porque cada uno solo ve su propio directorio.
Parte 2 — Dónde viven tus archivos y comandos
- 5
Inspecciona la copia completa bajo .claude/worktrees
Abre la carpeta en tu explorador de archivos: cada worktree es un checkout completo con su propio index.html, su propio .claude/settings.local.json y su propio archivo git, mientras la pesada base de objetos sigue compartida en el .git principal. Por eso crear otra copia es casi gratis.
Dos worktrees en el disco — clever-munching-toast y spicy-napping-otter — cada uno una copia completa del proyecto con su propia carpeta git y su index.html.Ver en 1:50 - 6
Confirma que los comandos se quedan en el worktree
Cuando la primera sesión abre su página en el navegador, el aviso de permiso muestra que la ruta apunta a .claude/worktrees/clever-munching-toast — no a tu checkout principal. Claude Code también impide que los subagentes editen el checkout principal directamente, y una de esas comprobaciones de aislamiento no se puede desactivar.
El diálogo de aprobación nombra la ruta exacta del worktree, la prueba de que la sesión uno solo toca su propia copia del proyecto.Ver en 1:42 - 7
Nombra worktrees o ramifica desde PRs (opcional)
claude --worktree feature-auth crea un worktree con nombre predecible, y ejecutar el mismo nombre otra vez lo reabre en vez de crear un duplicado. También puedes pasar un número de PR entre comillas (claude --worktree "#1234") o una URL de PR de GitHub/GitLab para obtener un worktree de ese pull request bajo .claude/worktrees/pr-<number>.
Parte 3 — Subagentes en paralelo y limpieza
- 8
Pide subagentes paralelos con aislamiento de worktree
El aislamiento escala más allá de las terminales. Un solo prompt — "lanza cinco subagentes distintos para crear cinco variantes y aprovecha el aislamiento de git worktree" — hace que Claude Code genere agentes Task, cada uno en su propio worktree aislado, trabajando sobre el mismo repo a la vez sin colisiones.
Cinco agentes Task lanzándose en paralelo, cada uno anunciado como trabajando en su propio git worktree aislado.Ver en 2:42 - 9
Observa cómo cada agente corre en su carril
La lista de tareas muestra las cinco variantes con usos de herramientas y conteos de tokens, así que ves el progreso sin abrir cinco terminales. Las transcripciones de los subagentes se quedan fuera del contexto del hilo principal, lo que mantiene pequeña la sesión orquestadora mientras los agentes hacen el trabajo pesado.
Los cinco subagentes a mitad de ejecución — la Variación 1 ya terminada con 50,3k tokens mientras los demás leen archivos en sus propios worktrees.Ver en 3:42 - 10
Compara las variantes y fusiona la ganadora
Cuando los agentes terminan, Claude Code lista cada variante con su ruta bajo .claude/worktrees/agent-<id>/, para que las abras en paralelo en el navegador. Publica la que te guste con un git merge normal de su rama de worktree (o con un PR) — los conflictos, si los hay, se resuelven como en cualquier merge de Git.
El resumen nombra cada variante y su ruta en .claude/worktrees, con un resultado renderizado abierto junto a la lista.Ver en 4:22 - 11
Guarda el aislamiento como subagente reutilizable
Para hacer permanente el aislamiento por worktree, solo pídelo: "crea un subagente desarrollador front-end, usa el modelo Haiku y haz que aproveche el aislamiento de worktree". Claude Code investiga su propia documentación de agentes y te escribe un archivo nuevo bajo .claude/agents/.
El lenguaje natural basta — Claude Code consulta su propia documentación sobre el formato de agentes personalizados antes de escribir el archivo.Ver en 5:42 - 12
Comprueba el isolation: worktree del frontmatter
El frontend-dev.md generado lleva name, description, model: haiku, una lista blanca de tools y — la línea nueva — isolation: worktree. Cada ejecución futura de este subagente ocurre ahora en un worktree temporal que se elimina automáticamente si termina sin cambios.
La línea 8 del frontmatter — isolation: worktree — es lo que da a cada ejecución de este subagente su propio worktree.Ver en 6:42 - 13
Fusiona y deja que Claude limpie
Al cerrar una sesión, Claude Code inspecciona el worktree: los worktrees sin nombre y limpios se eliminan automáticamente y cualquier cosa con trabajo pregunta si conservarla o eliminarla — al conservar imprime el comando claude --worktree <name> --resume para más tarde. Las ejecuciones headless con -p nunca limpian; esas elimínalas con git worktree remove.
Worktrees de Claude Code vs git worktree add manual
Los worktrees llevan años en Git — lo nuevo es que Claude Code gestiona todo su ciclo de vida. Las diferencias que importan:
- 1Creación: a mano ejecutas git worktree add ../project-feature -b feature, haces cd y arrancas Claude. Con claude --worktree la sesión aterriza en .claude/worktrees/<name> en un paso, con nombre tuyo o automático.
- 2Commit base: worktree.baseRef controla el punto de partida — fresh (por defecto) ramifica desde la rama por defecto del remoto; head incluye tus commits locales aún sin subir. El flag no puede apuntar a una rama concreta; la documentación dice que uses el git worktree add manual para eso.
- 3Dotfiles: un archivo .worktreeinclude en la raíz del proyecto copia los archivos ignorados por git, como .env, en cada worktree nuevo. Los worktrees hechos a mano no reciben ese tratamiento.
- 4Limpieza: Claude Code inspecciona el worktree al salir, elimina automáticamente los limpios sin nombre, pregunta antes de tocar el trabajo en curso y barre periódicamente los worktrees de subagentes abandonados. Los worktrees manuales son responsabilidad completamente tuya.
- 5Barandillas: las comprobaciones de aislamiento impiden que los subagentes editen el checkout principal, y al reanudar una sesión vuelves a su worktree. El git worktree add clásico no tiene red de seguridad equivalente.
Por debajo sigue siendo Git de toda la vida. El panel de control de código fuente de VS Code lista cada worktree con sus cambios, los merges son git merges normales y los worktrees hechos a mano y los de Claude coexisten en el mismo repositorio — elige la herramienta según la tarea.
Cuando un worktree no se comporta
La mayoría de los tropiezos son fundamentos de Git asomando, no bugs de la función. Estos cinco cubren casi todos los bordes ásperos que encontrarás:
- 1El push aterriza en main. Una rama de worktree nueva sigue a la rama por defecto de origin, así que un git push sin calificar puede apuntar a main. Haz push explícito con git push origin worktree-<name> y mantén main protegida.
- 2Faltan archivos o herramientas. Los archivos ignorados por git (.env, carpetas vendor) y los filtros locales del repo como LFS no se propagan a un worktree nuevo. Lístalos en .worktreeinclude, o ejecuta git lfs pull y tus comandos de configuración dentro del worktree.
- 3El arranque falla con un error de confianza. En un directorio no confiable claude --worktree sale con un error que te pide aceptar primero el workspace — apruébalo y reintenta. (Las ejecuciones no interactivas con -p se saltan la comprobación.)
- 4Dos worktrees chocan en el merge. Si ambas tareas editan el mismo archivo — rutas, una barra lateral, package.json — resolverás conflictos al fusionar, como en cualquier flujo de Git. Los worktrees eliminan las colisiones a mitad de ejecución, no las intenciones solapadas.
- 5Worktrees huérfanos tras ejecuciones headless. Las ejecuciones con -p nunca limpian tras de sí; bórralos a mano con git worktree remove (ejecuta antes git worktree unlock si alguno está bloqueado).
Borrar un worktree bajo los pies de una sesión tampoco es fatal: la próxima reanudación cae en el directorio de arranque y el vínculo se limpia. Nada más se rompe en la sesión.