Claude Code worktrees: guía de –worktree, .env y limpieza

Abres una terminal y le pides a Claude Code que arregle un bug del login. Abres otra y le pides la página de facturación. Las dos sesiones apuntan a la misma carpeta.

Diez minutos después, los tests de una fallan por un archivo que la otra toca a medias. La segunda hace git stash y se lleva el trabajo de la primera.

Los Claude Code worktrees resuelven justo eso: cada sesión con su carpeta y su rama, sin clonar el repo dos veces. Porque el problema no era el modelo. Era que pusiste a dos agentes a escribir en el mismo suelo.

En corto: arranca cada sesión con claude --worktree <nombre> y Claude Code crea un git worktree en .claude/worktrees/<nombre>/ con una rama nueva, así dos o tres agentes editan el mismo repo sin tocarse los archivos. Copia .env con .worktreeinclude, instala dependencias en cada worktree y dale a cada uno su puerto. Los conflictos no desaparecen: se aplazan al merge, donde decides tú.

¿Qué es un git worktree?

Un git worktree es un directorio de trabajo adicional, con su propia rama y sus propios archivos, que comparte el historial y la carpeta .git del repositorio principal.

No es un clon. Es otra copia de los archivos enlazada al mismo repo: un commit hecho en un worktree se ve al instante desde los demás. La documentación oficial de worktrees en Claude Code (consultada en octubre de 2026) pone el ejemplo típico: una sesión construye una feature mientras otra arregla un bug.

No confundas esto con los subagentes. En el post sobre cómo orquestar subagentes en Claude Code el tema era repartir trabajo dentro de una sesión. Aquí hablo de varias sesiones independientes, cada una en su terminal, aisladas a nivel de archivos. Y si lo que buscas es el método para repartir tareas entre agentes, está en cómo dirigir agentes de IA en paralelo sin conflictos. Este post es la mecánica: qué hace Claude Code cuando le pasas --worktree.

¿Cuándo usar Claude Code worktrees en vez de clones o subagentes?

Para sesiones paralelas sobre el mismo repo, los Claude Code worktrees son la forma más directa de aislar archivos sin duplicar el historial:

Criterio	Un checkout, varias ramas	Clones separados	Worktrees	Subagentes con isolation: worktree
Aislamiento de archivos	Ninguno	Total	Total por carpeta	Total por subagente
Historial	Compartido	Duplicado, sincronizas con push/pull	Compartido al instante	Compartido
Coste de arranque	Cero	Clonar + instalar	Checkout + instalar	Lo gestiona Claude Code
Riesgo principal	Una sesión pisa o hace stash del trabajo de otra	Clones desincronizados, disco duplicado	Dependencias, .env y puertos por worktree; conflictos en el merge	No conversas directamente con cada agente

¿Cómo se usan los Claude Code worktrees con --worktree?

claude --worktree es la opción de Claude Code que crea un git worktree en .claude/worktrees/<nombre>/, en una rama nueva worktree-<nombre>, y arranca la sesión dentro para que sus ediciones no toquen el checkout principal. Pásala con un nombre, o usa -w:

# Terminal 1
claude --worktree login-500

# Terminal 2
claude --worktree facturacion

# Terminal 3: sin nombre, Claude genera uno
claude -w

Según el changelog oficial, --worktree y el aislamiento de subagentes en worktree llegaron en la v2.1.49, y ExitWorktree en la v2.1.72. Comprueba tu versión con claude -v.

Tres detalles de la doc que conviene saber antes de empezar:

1. Base de la rama. Por defecto sale de la rama principal del remoto ("fresh"), no de tu rama actual. Para partir de tu trabajo local, pon "worktree": { "baseRef": "head" } en settings.json.
2. Desde una PR. claude --worktree "#1234" trae esa pull request y crea .claude/worktrees/pr-1234. Sin comillas, tu shell trata # como comentario.
3. Aislamiento real. Dentro de un worktree, Claude Code bloquea Edit, Write y NotebookEdit hacia el checkout principal, los comandos que se ejecutan en él y los comandos git redirigidos hacia él. No vigila un cp o una redirección de shell que escriba allí.

Añade .claude/worktrees/ a tu .gitignore. A mitad de sesión, pedirle a Claude que "trabaje en un worktree" activa la herramienta EnterWorktree.

El flujo manual con git worktree add

Usa git directamente cuando quieras partir de una rama existente o dejar el worktree fuera del repo. Comandos comprobados en un repo de prueba:

git worktree add ../mi-app-auth -b feat/auth   # rama nueva
git worktree add ../mi-app-bug fix/login-500   # rama existente

git worktree list
# .../mi-app       080ee12 [main]
# .../mi-app-auth  080ee12 [feat/auth]
# .../mi-app-bug   080ee12 [fix/login-500]

cd ../mi-app-auth && claude

Una rama solo puede estar activa en un worktree a la vez: si repites feat/auth en otro, git responde fatal: 'feat/auth' is already used by worktree at '<ruta>' (en versiones anteriores a la 2.42, «is already checked out at»). Es una protección, no un fallo.

node_modules, .env y puertos en cada worktree

Un worktree trae solo los archivos versionados. En la prueba, el .env del repo principal no aparecía en el worktree nuevo. Tampoco node_modules ni la carpeta de build.

Para .env, crea un .worktreeinclude en la raíz con sintaxis de .gitignore. Claude Code copia los archivos que coinciden y están ignorados por git. Solo funciona con los worktrees que crea Claude Code; con git worktree add lo copias tú. Si usas un hook WorktreeCreate, tampoco se procesa: cópialos dentro del hook.

.env
.env.local

Para node_modules, lo seguro es instalar en cada worktree. Lo rápido es worktree.symlinkDirectories, que enlaza la carpeta del repo principal en vez de duplicarla:

{
  "worktree": {
    "symlinkDirectories": ["node_modules"]
  }
}

Yo solo usaría el symlink si ninguna tarea cambia dependencias. Si una sesión instala un paquete, lo instala para todas.

Para los puertos, la doc no dice nada porque no es un problema de git. .worktreeinclude copia el mismo .env a todos los worktrees: si tu servidor lee PORT de ahí (Express con dotenv, por ejemplo), tres worktrees se pelean por el mismo puerto. Cambia el PORT en el .env de cada uno. Next.js no lee PORT del .env: arranca con npm run dev -- -p 3001. Vite y Next saltan solos al siguiente puerto libre, pero eso rompe lo que tenga el puerto apuntado en otro sitio: callbacks OAuth, CORS, el proxy del frontend. Lo mismo con bases de datos locales y contenedores: los worktrees aíslan archivos, no servicios.

Cómo integrar los cambios de cada worktree

Cada sesión termina con commits en su rama. Integras como con cualquier rama: pull request, o merge local desde el checkout principal.

# En el worktree
git add -A && git commit -m "feat: auth con refresh token"

# En el checkout principal
git merge --no-ff feat/auth
git merge --no-ff worktree-login-500   # si lo creó claude -w login-500

Aquí está la tesis: los worktrees no eliminan los conflictos, los mueven al merge. Mientras trabajan, cada agente vive en su burbuja. Si dos tocaron el mismo archivo, te enteras al integrar. Reparte las tareas por zonas del código que no se solapen e integra una rama cada vez, con los tests después de cada merge.

Si te falta la base de trabajar con Claude Code de idea a producto, es lo que recorre el curso Construye con IA.

Limpieza: qué borra Claude Code y qué te toca a ti

Claude Code solo limpia lo que no pierde trabajo. Al salir de una sesión con --worktree:

• Sin cambios y sin nombre de sesión: borra el worktree y su rama. Si le pusiste nombre a la sesión (claude -n o /rename), pregunta antes. El nombre del worktree no cuenta.
• Con cambios o commits: te pregunta si conservarlo. Si lo conservas, imprime claude --worktree <nombre> --resume para volver.
• Con -p: no hay pregunta al salir, así que no limpia nada.

Los worktrees de subagentes se borran solos si terminan sin cambios. Los que quedan, y los de sesiones que mandas a segundo plano, los revisa un barrido periódico cuando superan tu cleanupPeriodDays (30 días por defecto). Aun así, no borra ninguno con cambios o commits sin push. Tampoco toca nunca el worktree de una sesión --worktree en primer plano ni los que creaste con git worktree add.

Lo manual, comprobado en el mismo repo de prueba:

git worktree remove ../mi-app-auth
git worktree remove --force ../mi-app-bug   # con cambios sin commit
git worktree unlock <ruta>                  # si está bloqueado
git worktree prune                          # entradas de carpetas ya borradas
git branch -d feat/auth fix/login-500       # solo ramas ya integradas; -D fuerza

Un matiz de la prueba: git worktree remove se niega si hay archivos modificados o sin seguimiento, pero los ignorados (.env, node_modules) no lo frenan y desaparecen con la carpeta. Si cambiaste algo en el .env del worktree, guárdalo antes.

Límites de los Claude Code worktrees

Los worktrees resuelven el choque de archivos y nada más.

Cada worktree arranca en frío. Dependencias, build, caché y .env se preparan por worktree. En proyectos grandes son minutos y gigas por sesión. En monorepos, worktree.sparsePaths descarga solo las carpetas que necesita cada sesión.

La ubicación dentro del repo tiene efectos secundarios. En el issue #27282 de anthropics/claude-code, abierto en febrero de 2026 y todavía abierto, varios usuarios piden crear los worktrees en una carpeta hermana. Uno cuenta que webpack recorre el node_modules del worktree y se atasca; otro, que su formateador y sus linters se saltan el código porque .claude/worktrees/ está en .gitignore. Hoy la salida es un hook WorktreeCreate o git worktree add ../carpeta.

No aíslan servicios. Dos agentes que lanzan migraciones contra la misma base de datos local se pisan igual que antes.

Tu atención no escala. Tres sesiones son tres diffs que revisar. Sin una spec clara por tarea, el paralelismo multiplica la revisión.

No los uses para tareas que tocan los mismos archivos ni para cambios de cinco minutos, donde preparar el entorno cuesta más que la tarea.

Empieza hoy con dos sesiones

Elige dos tareas del backlog que no compartan archivos. Añade .claude/worktrees/ al .gitignore, crea el .worktreeinclude, lanza claude -w tarea-a y claude -w tarea-b en dos terminales y cambia el puerto en una. Integra una rama, pasa los tests, integra la otra.

El paso siguiente es que cada sesión arranque con un contrato, no con un prompt suelto: es lo que trabajamos en el Workshop SDD + Agentic Engineering. Tienes más sobre Claude Code avanzado en el canal de YouTube de Dominicode, y el flujo diario completo, en cómo usar Claude Code a diario.

Preguntas frecuentes

¿Qué versión de Claude Code necesito para usar --worktree?

El changelog oficial registra --worktree (-w) y el aislamiento de subagentes en worktree en la v2.1.49; el campo isolation: worktree en el frontmatter de un agente, en la v2.1.50. Otras piezas llegaron después: ExitWorktree en la v2.1.72 y los worktrees desde merge requests de GitLab en la v2.1.233. Actualiza con claude update.

¿Se copian .env y node_modules al worktree?

No por defecto. El worktree solo trae archivos versionados. El .env lo copias con un .worktreeinclude en la raíz, y node_modules lo instalas en cada worktree o lo enlazas con worktree.symlinkDirectories en settings.json.

¿Qué diferencia hay entre --worktree y un subagente con isolation: worktree?

Con --worktree diriges tú cada sesión en su terminal. Con isolation: worktree, la sesión principal lanza subagentes y cada uno recibe un worktree temporal que se borra si termina sin cambios.

¿Se borran solos los Claude Code worktrees?

Solo si están limpios. Al salir de una sesión sin cambios y sin nombre de sesión (-n o /rename; el nombre del worktree no cuenta), borra el worktree y su rama; si hay cambios, pregunta. Las ejecuciones con -p no limpian nada, y los worktrees creados con git worktree add los borras tú con git worktree remove.

---

Por Bezael Pérez — Developer senior con más de 15 años de experiencia y fundador de Dominicode.