Ejecutar sesiones paralelas con worktrees

​

Inicie Claude en un worktree

claude --worktree feature-auth

​

Configure el entorno del worktree

​

Pida a Claude que cree un worktree

​

Limpie worktrees

• El worktree está limpio: para una sesión sin nombre, Claude elimina el worktree y su rama automáticamente. Una sesión nombrada le solicita primero para que pueda mantener el worktree para más tarde
• El worktree tiene trabajo en él: Claude le solicita que mantenga o elimine el worktree. Mantener preserva el directorio y la rama para que pueda regresar más tarde. Eliminar borra el directorio del worktree y su rama, junto con todo el trabajo en ellos
• El estado del worktree no se puede verificar: cuando Claude Code no puede contar los cambios del worktree o no puede inspeccionar los checkouts de sus submódulos, le solicita en lugar de eliminar el worktree automáticamente. La solicitud nombra lo que no pudo verificar

​

Reanude una sesión de worktree

• Directorio de lanzamiento: reanude desde el checkout principal u otro directorio del repositorio. Claude Code reingresa a un worktree que creó con git bajo .claude/worktrees/ incluso cuando lanza desde dentro de él. Cuando lanza desde dentro de cualquier otro worktree, Claude Code lo reingresa solo si puede respaldarlo desde allí: un worktree que es su propio repositorio, uno sin metadatos de git, o un lanzamiento desde un subdirectorio de un worktree que creó con git worktree add se niega, por lo que lance esos desde el checkout principal.
• --fork-session: la sesión bifurcada comienza en el directorio desde el que lanzó Claude, y Claude Code deja el worktree de la sesión original sin cambios.
• Worktree eliminado: si el directorio del worktree ya no existe, Claude Code reanuda la sesión en el directorio desde el que lanzó Claude. Le dice que el worktree se ha ido y borra el enlace del worktree de la sesión.

​

Cómo Claude Code aplica el aislamiento

• Ediciones de archivos: Claude Code bloquea un Edit, Write, o NotebookEdit que apunta a una ruta en el checkout principal.
• Directorio de trabajo del comando: Claude Code bloquea un comando Bash, PowerShell, o Monitor cuyo directorio de trabajo se resuelve al checkout principal, o cuyo directorio de trabajo no puede verificar que permanece fuera de él.
• Redirecciones de git: Claude Code bloquea un comando Bash o Monitor que redirige git al checkout principal. La redirección puede venir a través de git -C, --git-dir, una variable GIT_DIR o GIT_WORK_TREE, o un cd al checkout principal antes de ejecutar git.
• Forma del comando: Claude Code bloquea un comando Bash o Monitor cuando no puede verificar desde el texto del comando que cualquier git que ejecute el comando permanece dentro del worktree. Eso sucede, por ejemplo, cuando el nombre del comando se calcula en tiempo de ejecución, cuando la sintaxis no se puede analizar, o cuando una expansión como ${!name} o ${ command; } podría ejecutar un comando que el texto no especifica. Claude Code le dice a Claude cómo reescribir el comando rechazado, como dividirlo en comandos simples y separados. No puede desactivar esta verificación.

​

Aisle subagentes con worktrees

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

​

Limpie worktrees de subagentes y sesiones en segundo plano

• El worktree aún contiene trabajo: archivos cambiados o sin seguimiento, o commits no enviados.
• Un submódulo extraído en el worktree contiene archivos cambiados o sin seguimiento, o Claude Code no puede inspeccionar los submódulos del worktree. Esta verificación requiere Claude Code v2.1.274 o posterior.
• Uno de los cuatro casos que también bloquean la creación de worktree se aplica: Claude Code no puede determinar qué controladores de filtro define la configuración del repositorio, o encuentra una configuración allí que no puede desactivar.
• El worktree pertenece a una sesión --worktree que no ha enviado al fondo, sin importar su antigüedad.
• Creó el worktree usted mismo con git worktree add, incluso si luego ejecutó una sesión --worktree <name> en él y envió esa sesión al fondo.

​

Personalice la creación de worktrees

​

Elija la rama base

• "fresh" (predeterminado): ramifique desde la rama predeterminada del repositorio en el remoto, generalmente main, para que el worktree comience desde un árbol limpio que coincida con el remoto.
• "head": ramifique desde su HEAD local actual, para que el worktree lleve sus commits no enviados y estado de rama de característica. Use esto cuando aisle subagentes que necesiten operar en trabajo en progreso. Dentro de un worktree, "head" se resuelve a ese HEAD del worktree, no al del checkout principal.

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

​

Ramifique desde una solicitud de extracción

claude --worktree "#1234"

• github.com: obtiene pull/<number>/head
• gitlab.com: obtiene merge-requests/<number>/head
• GitHub Enterprise, GitLab autogestionado, u otro host: intenta pull/<number>/head primero, luego merge-requests/<number>/head

​

Copie archivos ignorados por git en worktrees

.env
.env.local
config/secrets.json

​

Reutilice un nombre de worktree

• No tiene cambios sin confirmar ni archivos sin seguimiento.
• Todavía está en la rama que Claude Code creó para él.
• No tiene commits propios, o su solicitud de extracción o solicitud de fusión fue fusionada y su rama remota fue eliminada.

• El worktree falla cualquiera de las condiciones.
• Claude Code no puede verificar el estado del worktree.
• worktree.baseRef es "head".
• El nombre es una referencia de solicitud de extracción o solicitud de fusión.

​

Reemplace la creación de worktree con un hook

​

Qué comparten los worktrees con el checkout principal

• El directorio .git del repositorio: los comandos de git en un worktree escriben en el directorio .git compartido del repositorio principal, y el sandboxing permite esas escrituras, por lo que comandos como git commit funcionan desde dentro de un worktree con el sandbox habilitado.
• Plugins: los plugins instalados en ámbito de proyecto desde el checkout principal también se cargan en worktrees del mismo repositorio, por lo que no necesita reinstalarlos por worktree. Requiere Claude Code v2.1.200 o posterior.
• Aprobaciones de permisos: elegir “Sí, y no preguntar de nuevo” para un comando Bash en una sesión de worktree guarda la regla en el .claude/settings.local.json del checkout principal, por lo que se aplica en el checkout principal y en cada otro worktree del repositorio, y sobrevive a la eliminación del worktree. En Windows y en los otros casos donde Claude Code no usa la raíz del repositorio, la regla permanece con ese worktree. Antes de v2.1.211, una aprobación otorgada en un worktree se guardaba dentro de ese worktree, no se aplicaba en otro lugar, y se perdía cuando se eliminaba el worktree. Consulte dónde se guardan las aprobaciones.
• Skills, agentes y comandos sin seguimiento: cuando el checkout del worktree no tiene un directorio .claude/skills en su raíz, por ejemplo porque su .claude/skills está en gitignore, Claude Code carga los skills de proyecto del checkout principal en la sesión del worktree. En un worktree con su propio directorio .claude/skills, solo se carga esa copia. La misma lectura de paso cubre .claude/agents y .claude/commands. Para skills, la lectura de paso requiere Claude Code v2.1.277 o posterior.

​

Administre worktrees manualmente

git worktree add ../project-feature-a -b feature-a

git worktree add ../project-bugfix fix-issue-456

cd ../project-feature-a
claude

git worktree list

git worktree remove ../project-feature-a

​

Control de versiones no-git

{
  "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\"'"
          }
        ]
      }
    ]
  }
}

​

Solución de problemas

​

Claude Code no puede entrar en el worktree al iniciar

​

La creación de worktree falla en una ruta con enlace simbólico

​

Los archivos Git LFS son archivos de puntero en un worktree que Claude Code creó

• Could not read the repository git config to neutralize filter drivers: Claude Code no pudo leer el .git/config del repositorio, por ejemplo debido a sus permisos. Corrija eso e intente de nuevo.
• The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline): cambie el nombre o elimine ese controlador de filtro en .git/config e intente de nuevo.
• The repository git config has a conditional include (includeIf): mueva la configuración que el includeIf en .git/config extrae directamente a ese archivo, elimine el includeIf, e intente de nuevo. Un includeIf en su configuración de git global no activa esto.
• Git was not run: the repository's own git config sets <key>: el mensaje nombra una clave que apunta Git LFS a un programa para ejecutar, como lfs.customtransfer.<name>.path o lfs.standalonetransferagent. Si esa configuración es suya, muévala a su configuración de git global. Si no la reconoce, elimínela de la configuración de git del repositorio, ya que una herramienta o checkout que no confía puede haberla escrito. Reintente una vez que la clave se haya ido de la configuración del repositorio.

​

Claude Code se niega a usar un worktree

• Dice launch from the parent checkout o Run the resume from the project checkout: lanzó Claude Code desde dentro del worktree. Lance desde el checkout principal en su lugar; el worktree no necesita recreación.
• Dice it cannot be resumed or re-entered: nada en esta sesión respalda el worktree desde donde lanzó. Recréelo; el directorio y su trabajo permanecen en el disco para recuperación manual, y cuando el worktree tiene un checkout principal, reanudar desde allí también funciona.
• Dice it contains the protected checkout: el directorio rechazado es un padre de su checkout principal, como su directorio de inicio. No lo elimine. Cambie la ruta del worktree, como la ruta que devuelve su hook WorktreeCreate o el destino de EnterWorktree, para que el worktree no contenga el checkout.
• Dice the protected checkout <path> has a .git entry that could not be examined o has git metadata that could not be resolved: el problema es los metadatos de git del checkout principal, no los del worktree. No elimine el worktree, e ignore el consejo final del mensaje para recrearlo, que no se aplica a estos dos finales. Repare el checkout principal, por ejemplo un problema de permisos o un rechazo de git dubious ownership en su .git, e intente de nuevo.
• Dice its recorded path has a network spelling: Claude Code nunca reanuda en un worktree en una ruta de red. Recree el worktree en una ruta local.
• Cualquier otro final: el mensaje nombra el problema y su corrección, como eliminar una redirección core.worktree o recrear el worktree; sígalo. Antes de eliminar un directorio cuyo mensaje dice que su identidad de git no pudo ser verificada, aborde la causa nombrada primero, por ejemplo un enlace simbólico en la ruta del worktree o git en sí fallando al ejecutarse, ya que el directorio puede estar saludable. Cuando recree, rescate cualquier cambio que necesite del directorio anterior primero; permanece en el disco.

​

La sesión se reanuda fuera de su worktree

• Error: cannot resume into worktree <path>: ...This session was not started. para un rechazo que la tabla muestra como Did not re-enter. Claude Code borra el enlace del worktree antes de salir, y el error lo dice; la próxima vez que reanude la conversación, la sesión continúa en el directorio actual sin aislamiento de worktree. Antes de v2.1.260, Claude Code no escribía el enlace borrado, así que cada reintento de la misma reanudación fallaba con el mismo error. Si suprime escrituras de transcripción, la limpieza no puede ser guardada. El error entonces dice que el mismo comando será rechazado de nuevo, y nombra --fork-session e iniciar una nueva conversación como formas de continuar sin el worktree.
• Error: could not verify worktree <path> for this resume, so the resume was aborted... para Could not verify
• Error: ...The worktree binding is kept. para Could not re-enter
• Notice: the worktree <path> for this session no longer exists... para un worktree desaparecido; Claude Code lo imprime y continúa la sesión, como lo hace una reanudación interactiva

​

Véase también

• Subagentes: delegue trabajo a agentes aislados dentro de una sesión
• Mensajería entre sesiones: deje que las sesiones en sus worktrees pasen hallazgos entre sí
• Equipos de agentes: coordine múltiples sesiones de Claude automáticamente
• Administrar sesiones: nombre, reanude y cambie entre conversaciones
• Sesiones paralelas de escritorio: sesiones respaldadas por worktree en la aplicación de escritorio