EN · Read in English Explorar gratis

Receta · Intermedio · 15 min

Claude Code worktree: varios agentes en paralelo sin pisarse

Lanza varias sesiones de Claude Code en paralelo con claude --worktree, copia el .env con .worktreeinclude y limpia los worktrees sin perder trabajo.

Portada: Claude Code worktree: varios agentes en paralelo sin pisarse

Probado con Claude Code 2.1.316 · revisado

Ver los archivos en GitHub Gratis · licencia MIT

El problema

Quieres que una sesión de Claude Code construya una función mientras otra arregla un bug, pero si las dos trabajan en la misma carpeta se pisan los archivos y los cambios se mezclan. Abrir otra copia del repositorio a mano es lento, y en la copia nueva falta el .env.

La solución

Un git worktree es otra carpeta de trabajo con su propia rama que comparte el historial del repositorio. Si cada sesión vive en su worktree, no se pisan. Claude Code lo hace con un solo parámetro: claude --worktree <nombre> (o -w).

1. Tu primera sesión en paralelo en 2 minutos

Requisito: estar en un repositorio git. En la raíz del proyecto, abre una terminal y lanza claude --worktree arreglo-login. Claude Code crea la carpeta .claude/worktrees/arreglo-login/ en una rama nueva llamada worktree-arreglo-login y arranca la sesión dentro. Abre otra terminal y lanza claude --worktree nueva-api: ya tienes dos sesiones aisladas. Si no pones nombre, Claude genera uno como bright-running-fox.

cd ~/mi-proyecto
echo '.claude/worktrees/' >> .gitignore
# terminal 1
claude --worktree arreglo-login
# terminal 2
claude --worktree nueva-api
# revisar un PR en su propio worktree (comillas obligatorias)
claude --worktree "#1234"
# con tmux
claude --worktree docs --tmux

Las sesiones interactivas necesitan que hayas aceptado la confianza de la carpeta: si es la primera vez en ese repositorio, ejecuta claude una vez allí; con -p se omite esa comprobación.

Primer cambio recomendado: añade .claude/worktrees/ a tu .gitignore para que el contenido de los worktrees no aparezca como archivos sin seguimiento en tu checkout principal.

Si usas tmux, --tmux crea una sesión de tmux para el worktree (requiere --worktree; con iTerm2 usa paneles nativos, y --tmux=classic fuerza tmux tradicional). También puedes pedirlo en mitad de una conversación: «trabaja en un worktree», y Claude usa la herramienta EnterWorktree.

2. El .env que falta: .worktreeinclude

Un worktree es un checkout nuevo: solo trae archivos versionados. Tu .env, .env.local o un config/secrets.json ignorados por git no estarán, ni tampoco node_modules ni el entorno virtual de Python.

Para lo primero, crea un archivo .worktreeinclude en la raíz del proyecto con sintaxis de .gitignore:

.env
.env.local
config/secrets.json

Solo se copian los archivos que coinciden con un patrón y además están ignorados por git, así que nunca duplica archivos versionados. Se aplica a todos los worktrees que Claude Code crea con git: los de --worktree, los de subagentes y las sesiones en paralelo de la app de escritorio. No se aplica si creas el worktree a mano con git worktree add ni si un hook WorktreeCreate sustituye la creación (ahí copias los archivos en el script).

Cuidado con los patrones que empiezan por **/ cuando los archivos están dentro de una carpeta ignorada entera: escribe vendor/**/config.json en lugar de **/config.json (comportamiento corregido en la 2.1.239).

Para las dependencias, pide a Claude que las instale al empezar o ejecuta tú npm install, pip install o lo que use tu proyecto dentro de la carpeta del worktree.

3. ¿Desde dónde parte? worktree.baseRef y los PR

Por defecto, los worktrees nuevos parten de la rama por defecto del remoto (normalmente origin/main), no de tu HEAD: así empiezan limpios. Si no ha hecho fetch en 24 horas, Claude Code hace un fetch de esa rama (máximo cinco segundos) y, si falla, usa la referencia local; sin remoto configurado, usa tu HEAD local.

Si quieres que el worktree lleve tus commits sin subir o el estado de tu rama de trabajo, pon worktree.baseRef en "head" en tus ajustes:

{
  "worktree": {
    "baseRef": "head"
  }
}

No acepta un nombre de rama: para partir de una rama concreta, crea el worktree con git worktree add y lanza claude dentro.

Para revisar o continuar un pull request, pasa el número con # o la URL: claude --worktree "#1234". Las comillas son necesarias para que la shell no tome # como comentario. Claude Code descarga el commit del PR desde origin y crea .claude/worktrees/pr-1234. Desde la 2.1.233 también acepta URL de merge requests de GitLab. Si git o ssh necesitan contraseña o confirmar un host nuevo, falla con «Failed to fetch PR/MR»: carga tu clave en ssh-agent y haz un git fetch a mano una vez.

4. Salir y limpiar sin perder trabajo

Al salir de una sesión interactiva en un worktree, Claude Code revisa si borrarlo eliminaría trabajo: archivos cambiados o sin seguimiento, cambios en submódulos y commits nuevos.

Con -p no hay pregunta al salir: el worktree se queda y además bloqueado (git worktree list lo muestra como locked). Para quitarlo:

git worktree list                                   # muestra 'locked' si quedó bloqueado
git worktree unlock .claude/worktrees/prueba
git worktree remove .claude/worktrees/prueba         # --force si tiene cambios sin commit (¡se pierden!)
git branch -D worktree-prueba                       # solo si ya no necesitas la rama

Los worktrees de subagentes y de sesiones en segundo plano los limpia un barrido periódico cuando superan cleanupPeriodDays, salvo que tengan trabajo pendiente.

5. Subagentes aislados, /batch y qué se comparte

No solo las sesiones: los subagentes también pueden trabajar cada uno en su worktree. Pídelo («usa worktrees para tus agentes») o hazlo permanente con isolation: worktree en el frontmatter de un subagente de .claude/agents/. Cada uno recibe un worktree temporal que se borra solo si termina sin cambios.

.claude/agents/refactorer.md, un subagente siempre aislado:

---
name: refactorer
description: Aplica refactorizaciones mecánicas en muchos archivos
isolation: worktree
---
Aplica la refactorización pedida en todos los archivos afectados, ejecuta los tests e informa del resultado.

El comando /batch <instrucción> lleva esto al extremo: investiga el código, divide el trabajo en 5 a 30 unidades independientes, te presenta un plan y, al aprobarlo, lanza un subagente en segundo plano por unidad, cada uno en su worktree aislado.

Lo que comparten los worktrees con el checkout principal:

Mientras una sesión está aislada, Claude Code bloquea ediciones y comandos que apunten al checkout principal.

6. Cuándo SÍ y cuándo NO paralelizar

Sí:

No:

Un flujo razonable para empezar: una sesión principal donde planificas (modo plan) y una o dos en worktrees para tareas acotadas con un criterio de «hecho» claro (tests que deben pasar). Al terminar cada una, revisa el diff, haz commit en su rama y abre el PR o fusiona. Si necesitas que las sesiones se pasen información, la documentación describe mensajes entre sesiones; si solo quieres repartir trabajo dentro de una sesión, usa subagentes.

Compruébalo

Prueba reproducible en Linux, en un repositorio desechable:

mkdir -p /tmp/wt-demo && cd /tmp/wt-demo && git init -q
printf '.env\n.claude/worktrees/\n' > .gitignore
echo 'SECRETO=demo' > .env
echo '.env' > .worktreeinclude
echo hola > a.txt && git add . && git commit -qm init
claude -p -w prueba --model haiku "Responde solo: OK"
ls -a .claude/worktrees/prueba    # a.txt y .env copiado
git worktree list                 # [worktree-prueba] locked

Lo ejecutamos el 1-nov-2026 con Claude Code 2.1.316: creó .claude/worktrees/prueba en la rama worktree-prueba, copió .env gracias a .worktreeinclude y dejó el worktree marcado como locked; lo limpiamos con git worktree unlock, remove y branch -D. Sin remoto, partió del HEAD local, como indica la documentación. No hemos grabado todavía la parte interactiva: dos terminales a la vez, la pregunta de conservar o eliminar al salir, --tmux y --worktree "#<PR>" contra un repositorio con remoto en GitHub.

Por qué funciona

git worktree permite tener varias carpetas de trabajo de un mismo repositorio, cada una con su rama, compartiendo un único .git. Claude Code crea y borra esas carpetas por ti, copia lo que indicas en .worktreeinclude y encierra cada sesión en la suya, así que dos sesiones nunca escriben en los mismos archivos. Fuentes: worktrees, referencia del CLI, comandos, ajustes de worktree, subagentes y el CHANGELOG.

Errores típicos

Preguntas frecuentes

¿Dónde crea Claude Code los worktrees?

En .claude/worktrees/<nombre>/ en la raíz del repositorio, en la rama worktree-<nombre>. Para un PR, .claude/worktrees/pr-<número>.

¿Por qué mi worktree no tiene el .env?

Porque es un checkout nuevo con solo archivos versionados. Añade .env a .worktreeinclude (y debe estar ignorado por git).

¿Por qué el worktree no tiene mis últimos commits?

Por defecto parte de la rama por defecto del remoto. Pon worktree.baseRef en "head" para partir de tu HEAD.

¿Se borra mi trabajo al salir?

Solo si eliges eliminar. Si hay cambios, Claude Code pregunta; si está limpio y la sesión no tiene nombre, lo borra porque no hay nada que perder.

git worktree remove dice que está bloqueado

Las ejecuciones con -p y los agentes en marcha lo bloquean. Si ya no corre nada, git worktree unlock <ruta> y luego remove.

¿Funciona sin git?

Para SVN, Perforce o Mercurial hay que configurar los hooks WorktreeCreate y WorktreeRemove; en ese caso .worktreeinclude no se procesa.

¿Varios worktrees gastan más límite?

Sí: cada sesión hace sus propias peticiones. Vigílalo con /usage.

Toda la biblioteca