Git worktree en Claude Code: sesiones paralelas

La documentación contiene información práctica sobre cómo trabajar con Ailoot.

¿Qué es un git worktree en Claude Code?#

Lanzar varios agentes en paralelo en la misma carpeta es el problema básico del vibe-coding al ritmo de 2026. Los agentes de IA escriben código más rápido de lo que una persona puede seguir quién está tocando qué. Sin aislamiento de archivos, lanzar dos sesiones paralelas de Claude Code en un mismo directorio acaba con una sesión sobrescribiendo el trabajo de la otra.

Git worktree resuelve esto en el nivel del sistema de archivos. Tienes un directorio principal en el que trabajas. El comando claude --worktree feature-auth crea la carpeta .claude/worktrees/feature-auth/ en una rama aparte e inicia Claude Code allí. Los archivos quedan aislados. Los cambios de una sesión no son visibles para la otra hasta que los fusiones explícitamente.

La documentación oficial de Anthropic lo explica así:

Una pista para comprobarlo: si alguna vez te ha llegado un commit en el que la mitad de los archivos eran trabajo de otra persona, necesitas un worktree.

En qué se diferencia git worktree de una rama normal#

El flujo estándar de Git: estás en la rama main y ejecutas git checkout feature-x; Git sobrescribe los archivos de la copia de trabajo. Un npm run dev que esté ejecutándose deja de funcionar porque package.json ha cambiado. Guardas los cambios sin commit con git stash y esperas a que el IDE vuelva a indexar. Regresas a la rama anterior y todo vuelve a sobrescribirse, así que tienes que volver a hacer stash y pop.

Git worktree ofrece otra opción: en lugar de cambiar una carpeta entre ramas, creas una segunda carpeta para otra rama. El comando git worktree add ../project-feature-x feature-x crea el directorio ../project-feature-x/ con los archivos de la rama feature-x. Tu main se queda en la carpeta original y el servidor de desarrollo sigue funcionando.

Antes, había que configurar manualmente el modo worktree en Claude Code: git worktree add, luego cd y después claude; había que repetirlo en cada terminal. La opción --worktree (también -w) hace las tres cosas con un solo comando.

Inicia la primera sesión en paralelo: la opción --worktree#

Ejemplo mínimo. Abre el primer terminal en la raíz del proyecto:

claude --worktree feature-auth

Claude Code hace tres cosas:

1. Crea .claude/worktrees/feature-auth/ con una instantánea de origin/HEAD (normalmente, tu rama predeterminada).
2. Crea una rama nueva worktree-feature-auth.
3. Inicia la sesión en esa carpeta.

Abre un segundo terminal en la misma carpeta raíz del repositorio:

claude --worktree bugfix-123

Listo. Dos sesiones de Claude Code, archivos distintos en el disco y ramas de Git distintas. Si escribes la autenticación en la primera y corriges una prueba fallida en la segunda, físicamente no pueden estorbarse.

Si no quieres escribir un nombre, Claude inventará uno:

claude --worktree
# → creates something like .claude/worktrees/bright-running-fox/

Un consejo para quienes empiezan con Git: añade .claude/worktrees/ a .gitignore. De lo contrario, al ejecutar git status en la carpeta principal, verás el contenido de todos los worktrees como archivos sin seguimiento:

# .gitignore
.claude/worktrees/

Un problema que debes evitar: antes de lanzar --worktree por primera vez en un directorio nuevo, entra con un claude normal (sin la opción) y acepta el diálogo de confianza del espacio de trabajo. Si no lo haces, la opción falla con un error «trust not accepted», incluso si la combinas con -p para el modo sin interfaz.

Dónde se encuentran los worktrees y cómo localizarlos#

La ubicación predeterminada es fija: .claude/worktrees/<value>/ en la raíz del repositorio. Si tu proyecto está en ~/dev/my-app/, el worktree feature-auth estará en ~/dev/my-app/.claude/worktrees/feature-auth/.

Para estructuras no estándar (por ejemplo, si quieres que el worktree esté fuera del repositorio), existe el hook WorktreeCreate; hablaremos de él más adelante en la sección sobre SVN y Mercurial.

Dentro de una sesión de Claude, puedes cambiar a otro worktree existente. Solo tienes que decir en el chat: «switch to .claude/worktrees/bugfix-123», y Claude llamará a la herramienta EnterWorktree. La carpeta actual no se tocará; puedes volver del mismo modo.

El comando estándar de Git muestra una lista de todos los worktrees, incluido el principal y los creados manualmente:

git worktree list

El resultado será parecido a este:

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

Copiar .env y los secretos: el archivo .worktreeinclude#

Cuando --worktree crea una carpeta nueva, solo incluye lo que se ha guardado en Git. .env, que contiene claves de API, y .env.local, que contiene la configuración local, aparecen en .gitignore, así que no están en el worktree. Por eso, el primer npm run dev falla con «MISSING DATABASE_URL».

La solución casera consiste en copiar .env manualmente después de cada --worktree. Funciona una vez y luego se olvida. La solución de Anthropic es crear un archivo .worktreeinclude en la raíz del proyecto con la lista de archivos ignorados por Git que se copiarán automáticamente a cada worktree nuevo.

Crea un archivo .worktreeinclude en la raíz del repositorio:

.env
.env.local
config/secrets.json

La sintaxis es la misma que la de .gitignore. Puedes usar patrones glob:

.env*
*.local
config/*.json
.vscode/settings.json

Anthropic da una regla clara para evitar accidentes:

En otras palabras, no puedes copiar package.json por accidente mediante .worktreeinclude: no está en .gitignore. Es seguro poner ahí cualquier patrón.

El mismo .worktreeinclude funciona en tres modos: el --worktree manual, los worktrees automáticos para subagentes (ver más abajo) y las sesiones de la aplicación de escritorio de Claude.

Worktree a partir de una pull request para revisar código#

Un escenario típico de revisión de código: un compañero ha enviado una PR; tienes que inspeccionar el código, ejecutar pruebas y dejar un comentario. Con un git checkout pull/1234/head normal, vuelves a cambiar la copia de trabajo e interrumpes tu sesión activa.

Con la opción --worktree, basta con un comando:

claude --worktree "#1234"

Esto es lo que ocurre: Claude Code ejecuta git fetch origin pull/1234/head, crea un worktree en .claude/worktrees/pr-1234/ y cambia a la rama de la PR. Se inicia la sesión. Puedes pedirle de inmediato que «lea el diff, ejecute las pruebas y busque errores lógicos»; mientras Claude trabaja, tu sesión principal en main sigue funcionando.

La sintaxis alternativa es la URL completa de la pull request:

claude --worktree https://github.com/OWNER/REPO/pull/1234

En un proyecto real, combinar claude --worktree "#N" con tu propio subagente de revisión de código te da una revisión automática en uno o dos minutos. Lánzalo en segundo plano, sigue trabajando en la ventana principal y vuelve al resultado con claude agents.

Rama base: worktree.baseRef para fresh o head#

La configuración predeterminada es la siguiente: cada worktree nuevo parte de origin/HEAD. La ventaja es empezar desde una base limpia que, con seguridad, coincide con lo que verá CI. El inconveniente es que, si tienes cambios sin commit o varios commits locales por delante del remoto en tu rama actual, no se incluirán en el nuevo worktree.

Para iniciar un worktree desde tu commit HEAD local actual, añade esto a .claude/settings.json (o a los ajustes globales):

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

Ahora claude --worktree experimental-feature parte del HEAD local actual. Es útil si tu función ya tiene commits locales sin enviar. No incluye ediciones seguidas aún sin commit. Si el subagente las necesita, consérvalas y transfiérelas expresamente; después inspecciona el diff de destino. No confundas esa transferencia con .worktreeinclude, que gestiona archivos locales ignorados.

El ajuste acepta exactamente dos valores: "fresh" (= origin/HEAD) y "head" (= el HEAD local). No admite referencias arbitrarias como "feature-branch" ni un hash de commit. Es una limitación deliberada para evitar una explosión combinatoria de opciones.

Aislar subagentes automáticamente: isolation: worktree#

Cuando le dices a Claude «lanza tres subagentes: uno lee la base de datos, el segundo revisa la API y el tercero comprueba las pruebas», los tres trabajan en tu copia de trabajo de forma predeterminada. Si solo dos modifican el mismo archivo al mismo tiempo, surge un conflicto. La solución es asignar automáticamente un worktree propio a cada uno.

Método 1: pedirlo verbalmente. Escribe a Claude en la conversación:

Usa worktrees para tus agentes.

Claude aplicará el aislamiento a todos los subagentes posteriores de esta sesión.

Método 2: configurarlo explícitamente en el propio subagente. En el archivo del subagente (por ejemplo, .claude/agents/code-reviewer.md), añade un campo al frontmatter:

---
name: code-reviewer
description: Reads the diff and writes code review comments
isolation: worktree
---

Eres un revisor meticuloso. Lee el diff y busca errores de lógica...

A partir de entonces, cada vez que se lance este subagente recibirá un worktree temporal en .claude/worktrees/. Si no ha escrito nada, la carpeta se elimina automáticamente al terminar. Si hay cambios sin commit, Claude preguntará si quieres conservarlos o eliminarlos.

La rama base de los worktrees de subagentes es la misma que para --worktree: de forma predeterminada, origin/HEAD; con worktree.baseRef: head, el HEAD local.

Matriz de decisión: worktree, /bg, subagente o Agent View#

Combinaciones habituales:

• «2 funciones en paralelo, manualmente» — dos terminales, cada uno ejecutando claude --worktree. El caso más sencillo.
• «Inicia una refactorización durante la noche; cerraré la aplicación» — /bg + /goal con una condición de finalización. La sesión funciona independientemente de tu ventana.
• «Un prompt, tres investigaciones en paralelo» — tres subagentes con isolation: worktree. Cada uno en su propio entorno aislado.
• «¿Qué está ejecutándose ahora?» — claude agents. Un panel con todas las sesiones y los filtros «running», «blocked» y «done».

5 problemas al trabajar con worktrees#

1. Has iniciado un worktree, falta .env y nada funciona. Es el problema más habitual. Un worktree es un checkout nuevo sin archivos ignorados por Git. En cuanto configures el modo worktree, añade un archivo .worktreeinclude con .env* y las configuraciones locales necesarias. Comprueba que el archivo esté en la raíz del repositorio, no en .claude/.

2. Quieres cambiar a la rama principal, ejecutas cd hasta la raíz y pierdes tus cambios sin commit en el worktree. La carpeta raíz y el worktree son dos copias de trabajo distintas. Volviste con cd; los cambios del worktree se quedaron donde estaban, no desaparecieron. Pero si te confundiste y ejecutaste git stash en la carpeta principal creyendo que estabas en el worktree, el stash se creará en la rama principal, no en la que esperabas.

3. Has iniciado 5 sesiones en paralelo y no recuerdas qué hace cada una. La documentación de Anthropic advierte explícitamente que la mayoría de los desarrolladores no pueden gestionar cognitivamente más de 2–3 sesiones. Una señal de sobrecarga es abrir Agent View y no poder decir de inmediato qué está haciendo cada agente. Limítate a dos sesiones simultáneas. Si la tarea requiere más, debe coordinarse mediante /goal + subagentes, no manualmente.

4. Los worktrees iniciados con -p (modo sin interfaz) no se limpian automáticamente. El comando claude --worktree feature-x -p "do thing" no muestra un aviso interactivo al salir, así que Claude nunca pregunta «¿elimino el worktree?». Estos worktrees se acumulan. Límpialos manualmente: git worktree remove .claude/worktrees/feature-x. También puedes usar un script cron que elimine cualquier elemento con más de 7 días.

5. Diálogo de confianza en una carpeta nueva. Si abres el repositorio por primera vez y ejecutas claude --worktree de inmediato, el comando fallará. Ejecuta claude sin opciones, acepta la confianza del espacio de trabajo y sal; después --worktree funcionará. Es intencional: así Claude no obtiene acceso al proyecto de otra persona sin el consentimiento del usuario.

Limpieza: qué se elimina automáticamente#

La lógica de limpieza depende de lo que hayas hecho en el worktree y de cómo hayas iniciado la sesión. La documentación de Anthropic enumera tres situaciones:

Situación 1: entraste, no hiciste nada y saliste; el worktree se eliminó.

Situación 2: trabajaste un poco y no hiciste commit; al salir, Claude preguntará «¿conservar o eliminar?». «Conservar» guarda la carpeta y la rama para más adelante. «Eliminar» borra el directorio junto con los cambios sin commit y los commits nuevos. Es destructivo: no pulses «eliminar» por costumbre.

Situación 3: iniciaste con -p (modo sin interfaz) y el comando terminó. El worktree permanece. Límpialo manualmente:

git worktree remove .claude/worktrees/feature-x

Además, la limpieza en segundo plano elimina automáticamente los worktrees de subagentes y sesiones /bg si tienen más de cleanupPeriodDays días (un ajuste que normalmente es de 30 días de forma predeterminada) y no contienen trabajo sin guardar. La limpieza automática no toca los worktrees de --worktree; son responsabilidad tuya.

Alternativas para SVN, Perforce y Mercurial: el hook WorktreeCreate#

Si el repositorio usa Subversion o Mercurial, la opción --worktree no funcionará directamente. Anthropic ofrece un punto de extensión mediante dos hooks: WorktreeCreate (crea una copia aislada) y WorktreeRemove (la elimina).

Ejemplo de hook SVN de la documentación oficial:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

El hook lee el nombre del worktree por stdin ({ "name": "feature-auth" }), ejecuta svn checkout en un directorio calculado de antemano e imprime la ruta por stdout; Claude Code la utiliza como directorio de trabajo de la nueva sesión.

Una advertencia importante: si usas tu propio hook, no se utiliza .worktreeinclude. Si necesitas .env u otros archivos ignorados por Git en la carpeta nueva, cópialos dentro del propio script del hook.

Qué viene después: tres mecanismos de paralelismo relacionados#

Worktree proporciona aislamiento de archivos. /bg proporciona aislamiento del contexto. Los subagentes proporcionan aislamiento de tareas. Cada mecanismo resuelve un problema por separado. Juntos ofrecen una forma de trabajar en tres a cinco tareas en paralelo sin colapso cognitivo. Estas son las habilidades que sustentan el vibe-coding avanzado en 2026.

Este tema enlaza de forma natural con otros tres: cómo configurar un agente autónomo con /goal y Agent View, cómo crear tus propios subagentes para tus tareas y cómo lanzar cientos de agentes mediante Dynamic Workflows.

Abrir Ailoot.