Sesiones de Claude Code en paralelo con git worktrees

Dos sesiones de Claude Code editando la misma carpeta se pisan. Un worktree de git lo evita: es un directorio de trabajo aparte, con sus propios archivos y su propia rama, que comparte el historial y el remoto del mismo repositorio. Si cada sesión corre en su propio worktree, una puede construir una función mientras otra arregla un error.

Empieza una sesión en un worktree

Pasa --worktree (o -w) con un nombre:

claude --worktree feature-auth

Por defecto el worktree se crea en .claude/worktrees/feature-auth/, en la raíz del repositorio, con una rama nueva llamada worktree-feature-auth. Si repites el comando con otro nombre en una segunda terminal, tienes una segunda sesión aislada. Si no pones nombre, Claude se inventa uno.

• Añade .claude/worktrees/ a tu .gitignore para que el contenido de los worktrees no salga como archivos sin seguimiento en tu copia principal.
• La primera vez en un directorio, ejecuta claude una vez y acepta el diálogo de confianza; si no, un --worktree interactivo termina con un error que te lo pide.
• También puedes pedirlo dentro de una sesión: «trabaja en un worktree».

Un worktree es una copia nueva

Los archivos ignorados por git, como .env, no están, y las dependencias no están instaladas. Pídele a Claude que las instale o ejecuta tu preparación en la carpeta del worktree. Para copiar archivos ignorados de forma automática, pon un archivo .worktreeinclude en la raíz del repositorio, escrito como un .gitignore:

.env
.env.local

Solo se copian los archivos que coinciden con un patrón y están ignorados por git, así que los archivos con seguimiento nunca se duplican. Copia, no enlaza, así que limítalo a los pocos archivos pequeños que necesites. El ejemplo de la propia documentación incluye un archivo de secretos, así que piénsalo antes de añadir nada sensible. Para carpetas grandes como node_modules, la documentación apunta a un ajuste worktree.symlinkDirectories, o puedes dejar el comando de instalación en tu CLAUDE.md.

¿De qué rama parte?

Por defecto un worktree nuevo parte de la rama por defecto del repositorio en el remoto, normalmente main, así que empieza limpio. Si debe llevar tus commits sin subir, pon worktree.baseRef a "head" en tus ajustes. El ajuste solo admite esos dos valores. Para partir de una rama concreta que ya existe, crea el worktree tú mismo con git.

Qué comparte un worktree con tu copia principal

• El directorio .git del repositorio, así que git commit funciona dentro de un worktree.
• Los plugins instalados a nivel de proyecto.
• Las aprobaciones de permisos. Si eliges «Yes, and don't ask again» para un comando en una sesión de worktree, la regla se guarda en el .claude/settings.local.json de la copia principal, así que vale en todos los worktrees del repositorio y sobrevive al worktree. En Windows, y en algunos otros casos, la regla se queda con ese worktree. Mira la guía de modos de permisos para saber cómo funcionan los permisos.
• Las skills, agentes y comandos del proyecto, en algunos casos, cuando el worktree no tiene los suyos.

Mantiene la sesión dentro de su worktree

Mientras una sesión está aislada, Claude Code bloquea las ediciones que apuntan a una ruta de la copia principal, los comandos cuyo directorio de trabajo resuelve a la copia principal y los comandos de git redirigidos hacia ella. La documentación es clara sobre el límite: lee rutas y el texto de los comandos, y no sigue qué archivos escribe un comando de shell. Un simple cp o una redirección de shell hacia la copia principal no lo rechazan estas comprobaciones. Esos comandos quedan bajo tus permisos normales y tus ajustes de sandbox.

Limpieza

Cuando sales de una sesión interactiva de worktree, Claude Code comprueba si hay trabajo que se perdería al borrarlo. Si el worktree está limpio y la sesión no tenía nombre, borra el worktree y su rama. Una sesión con nombre te pregunta antes. Si hay cambios o commits nuevos, te pregunta si conservarlo o borrarlo, y borrarlo elimina el directorio y su rama junto con ese trabajo. Para volver a un worktree que conservaste, ejecuta el comando claude --worktree <nombre> --resume que imprime al salir.

Una excepción: una ejecución no interactiva (claude -p --worktree, mira ejecutar desde un script) no tiene pregunta al salir, así que esos los borras tú con git worktree remove <ruta>. Si git dice que el worktree está bloqueado, ejecuta antes git worktree unlock <ruta>.

Subagentes en su propio worktree

Pídele a Claude «usa worktrees para tus agentes», o hazlo permanente en un subagente propio añadiendo isolation: worktree a su cabecera. Cada subagente recibe un worktree temporal que se borra solo cuando termina sin cambios.

Bueno saber

• Los worktrees aíslan solo las ediciones de archivos. Los subagentes reparten el trabajo dentro de una sesión, y la documentación compara los enfoques en su página de agentes en paralelo.
• Necesitan un repositorio git. Otros sistemas de control de versiones necesitan hooks que sustituyan los pasos de git.
• Algún comportamiento cambió entre versiones, así que mira la documentación de la tuya.

Pruébalo con algo inofensivo

1. En un repositorio de prueba pequeño, añade .claude/worktrees/ al .gitignore.
2. Ejecuta claude -w prueba-uno, pide un cambio mínimo y sal. Elige conservar el worktree cuando pregunte.
3. Ejecuta git worktree list para verlo y claude -w prueba-uno --resume para volver.

Esta página sigue la documentación de worktrees de Anthropic tal como la leemos en octubre de 2026. No tenemos relación con Anthropic. La escribimos a partir de la documentación y no hemos probado todos los casos. Donde esta página y la documentación no coincidan, manda la documentación.

Mira también: Flujos de cada día · Claude Code en un código grande · Sesiones de Claude Code: reanudar, nombrar, ramificar.

La skill gratis loop-stop da a las tareas largas un límite y una regla de parada. Si quieres una segunda mirada a tu CLAUDE.md y a tus ajustes, el Tune-Up Kit es una lista de comprobación para eso (la ficha está en inglés).