Sesiones paralelas de Claude Code con git worktrees, dos ramas a la vez sin conflicto

Tienes dos hilos abiertos en el repo, una feature y un bugfix, y los dos necesitan a Claude. Abres dos terminales, claude en ambas, y al instante las dos sesiones están escribiendo en los mismos archivos. De repente una sesión cambia algo que la otra estaba a punto de leer y el estado se va al traste. Justo para eso existe, desde Claude Code v2.1.143, el flag --worktree. Cada sesión recibe su propio directorio de trabajo en su propia rama y solo comparte el historial de git.

El patrón no es nuevo, git worktree existe desde Git 2.5. Lo nuevo es que ahora Claude Code lo gestiona por sí mismo, incluidos la limpieza, el aislamiento de subagentes y el patrón de copia para archivos .env. Yo lo uso en producción desde hace 3 semanas y puedo tener 2 o 3 sesiones en paralelo al día sin que se produzca deriva.

1. Comprobar los requisitos

Necesitas Claude Code como mínimo en la v2.1.143 y un repo de git. Comprueba:

claude --version
# debe indicar >= 2.1.143, en vivo ahora mismo está 2.1.148

Si tu versión es más antigua, actualiza primero. Para eso tenemos un playbook propio: Estrategia de updates de Claude Code. Fuera de un repo de git, --worktree no funciona en modo por defecto, ahí necesitas un hook WorktreeCreate para SVN/Mercurial/Perforce. Para el 95 por ciento de los setups, git es lo predeterminado.

2. Aceptar una sola vez la confianza del repo

La primera vez que lo ejecutas en un directorio nuevo, Claude lanza un diálogo de confianza del workspace. Ese diálogo tiene que estar confirmado ANTES de que uses --worktree, si no el comando sale con un error. Así que, una vez:

cd /pfad/zu/deinem/repo
claude
# Trust-Dialog akzeptieren, danach Session beenden

Este paso me costó 15 minutos en el primer intento porque no supe ubicar el error. --worktree dice simplemente "trust not accepted" y sale, y eso no está explicado en ningún sitio.

3. Ampliar el .gitignore

Por defecto, Claude crea los worktrees en .claude/worktrees/<name>/. Si no lo añades al .gitignore, todos los contenidos del worktree aparecen como archivos sin seguimiento en tu checkout principal y el estado se vuelve ilegible. Añade esta única línea:

.claude/worktrees/

Es la recomendación oficial y es una sola línea, así que por favor no te olvides.

4. Arrancar el primer worktree

En el directorio principal de tu repo:

claude --worktree feature-auth

Claude crea ahora .claude/worktrees/feature-auth/, ramifica desde origin/HEAD a una rama nueva worktree-feature-auth y arranca la sesión en ese directorio. Puedes editar código como si fuera un checkout normal. La sesión está completamente aislada de tu checkout principal.

Si omites el nombre (claude --worktree sin argumento), Claude genera un nombre aleatorio del estilo bright-running-fox. Práctico para experimentos rápidos, poco práctico cuando mañana quieras volver a encontrar ese worktree. Mi recomendación: pon siempre un nombre.

5. Abrir un segundo worktree en paralelo

Segunda terminal, la misma ruta del repo, otro nombre:

claude --worktree bugfix-123

Ahora hay dos sesiones corriendo en paralelo. Cada una tiene su propio subconjunto de archivos, cada una escribe en su propia rama, no se estorban. Si cambias un archivo en la sesión 1 y abres ese mismo archivo en la sesión 2, en la sesión 2 ves el estado sin modificar del archivo tal como está en la base de la rama. Ese era exactamente el objetivo.

6. .worktreeinclude para los archivos .env

Por defecto, un worktree es un checkout nuevo, así que faltan todos los archivos ignorados por git. Tu .env, .env.local, las configuraciones locales, los secretos, todo desaparecido. El resultado es que tu app no arranca dentro del worktree porque no hay ninguna URL de base de datos configurada.

Solución: crea en la raíz del repo un archivo .worktreeinclude, con la misma sintaxis que .gitignore. Ejemplo:

.env
.env.local
config/secrets.json

Estos archivos se copian al nuevo worktree en cada llamada de --worktree, siempre que estén ignorados por git (los archivos con seguimiento nunca se duplican). Mi consejo: escribe el .worktreeinclude directamente durante el primer setup de worktree, si no dentro de 4 semanas tendrás el problema de que tu worktree nuevo arranca sin .env y necesitarás 20 minutos hasta entender por qué.

7. Activar el aislamiento de subagentes

Si tu sesión lanza subagentes (tienes un subagente para tests, otro para lint, otro para documentación), esos subagentes que corren en paralelo pueden escribir en tus archivos y sobrescribirse entre ellos. Solución: deja que los subagentes corran en worktrees propios.

Variante A (por sesión): di en la sesión "use worktrees for your agents". Claude mete cada subagente en un worktree temporal.

Variante B (permanente, para un subagente propio): añade esto al frontmatter del archivo del subagente:

---
name: test-runner
isolation: worktree
---

Los worktrees de subagentes se eliminan automáticamente cuando el subagente termina sin cambios. Si un subagente tiene cambios sin commitear, Claude te pregunta durante la limpieza.

El patrón de subagentes también lo hemos explicado en un playbook propio: Tu primer sub-agente en 30 minutos.

8. Configurar la rama base

Por defecto, los worktrees ramifican desde origin/HEAD, es decir, desde la main remota. Eso es limpio, siempre arrancas desde el último estado publicado. A veces, sin embargo, quieres ramificar desde tu HEAD local, por ejemplo cuando estás sobre una rama de feature y quieres aislar un subagente encima de ella. Configura en ~/.claude/settings.json o en el proyecto:

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

Solo se permiten "fresh" (por defecto, desde origin/HEAD) y "head" (desde el HEAD local). No puedes indicar una referencia de git cualquiera. Si necesitas eso, usa un git worktree add manual (paso 10).

9. Abrir un worktree para un PR

Lo descubrí la semana pasada y me parece genial. Quieres revisar un pull request, reproducir código o adaptarlo:

claude --worktree "#1234"

Claude hace fetch de pull/1234/head desde origin y crea el worktree en .claude/worktrees/pr-1234. También puedes pasarle la URL completa del PR de GitHub. Te ahorra el trasteo manual de git fetch + worktree add + checkout.

Encaja bien con nuestro playbook Pull request reviews con Claude Code.

10. Limpieza y gestión manual

Si cierras la sesión limpiamente y no has hecho ningún cambio, Claude retira el worktree y la rama automáticamente. Si hay cambios o commits, Claude pregunta: conservar el worktree (por defecto) o borrarlo.

En ejecuciones no interactivas (claude -p sin terminal) no se limpia nada, porque no es posible ninguna pregunta. Ahí tienes que ponerte tú:

git worktree list
# zeigt alle aktiven Worktrees
git worktree remove .claude/worktrees/feature-auth
# entfernt einen

La variante manual sin el flag --worktree, para cuando quieres control total sobre ruta y rama:

git worktree add ../mein-projekt-feature-a -b feature-a
cd ../mein-projekt-feature-a
claude

No lo olvides: cada worktree es un checkout nuevo, así que necesitas una vez npm install, pnpm install, python -m venv o lo que sea que pida tu setup. Yo me he escrito para eso un pequeño script de shell que ejecuta pnpm install automáticamente después de crear el worktree, y eso ahorra 2 minutos por worktree.

Qué viene ahora

Cuando domines el flujo de worktrees, merece la pena dar el salto a equipos de agentes realmente paralelos. Eso se pone interesante cuando no solo aíslas archivos, sino que además necesitas coordinación entre varias sesiones de Claude. Nuestro playbook Tu primer sub-agente en 30 minutos es la entrada, y después merece la pena Hooks contra alucinaciones como siguiente paso para asegurar el ciclo de vida del worktree.

Si todavía no has hecho nada con el comando git worktree, también tenemos una introducción suave a git para flujos de trabajo con IA: Git para IA, quickstart en 30 minutos.

Fuente

Documentación oficial de Anthropic: https://code.claude.com/docs/en/worktrees (estado a 2026-05-22). Referencia de settings para worktree.baseRef: https://code.claude.com/docs/en/settings. Gestión manual de worktrees con git: https://git-scm.com/docs/git-worktree.