Worktrees en Claude Code: sesiones en paralelo sin conflictos de edición

Qué es un worktree en Claude Code

Git admite worktrees desde hace años: git worktree add hace checkout de una rama en un segundo directorio, respaldado por los mismos datos de .git. Claude Code se apoya en eso. Con --worktree (o -w) crea el worktree por ti, inicia la sesión dentro, bloquea las ediciones que acabarían en tu checkout principal y te ofrece limpiarlo al salir.

Los worktrees aíslan archivos, nada más. Para repartir una tarea entre varios trabajadores dentro de una misma conversación, usa subagentes; para comparar las opciones, mira varios agentes de Claude Code.

• Ubicación por defecto: .claude/worktrees/<name>/, en la raíz del repositorio.
• Nombre de rama por defecto: worktree-<name>. Si no das un nombre, Claude Code elige uno, como bright-running-fox.
• Compartido con tu checkout: el directorio .git (así los commits y las ramas se ven desde todas partes), los plugins del proyecto y las aprobaciones de permisos de "no volver a preguntar".
• No compartido: todo lo que esté en .gitignore, como .env, node_modules y los artefactos de build. Un worktree es un checkout recién hecho.

El flujo con worktrees, paso a paso

1. Ignora la carpeta de worktrees

   Añade .claude/worktrees/ a .gitignore, para que los archivos de los worktrees no aparezcan como sin seguimiento en tu checkout principal. Si nunca has ejecutado Claude en este repositorio, ejecuta claude una vez antes para aceptar el aviso de confianza del espacio de trabajo; hasta entonces, las ejecuciones interactivas con --worktree se cierran.

2. Inicia una sesión por tarea

   Ejecuta claude --worktree <name> en una terminal para cada tarea. Si lo vuelves a ejecutar con un nombre que ya existe, reabre ese worktree en lugar de crear uno nuevo. También puedes pedirle a Claude a mitad de sesión que "trabaje en un worktree", y se mueve a uno con la herramienta EnterWorktree.

   # Dos sesiones aisladas, cada una en su propia terminal
   claude --worktree feature-auth
   claude --worktree fix-flaky-test
   
   # Crea un worktree a partir del pull request 1234 (pon el # entre comillas)
   claude --worktree "#1234"
   
   # Deja los worktrees fuera de git status
   echo ".claude/worktrees/" >> .gitignore

3. Lleva contigo los archivos sin seguimiento

   Enumera los archivos ignorados por git que necesita el proyecto, como .env y .env.local, en un archivo .worktreeinclude en la raíz del repositorio, con la sintaxis de .gitignore. Claude Code copia los archivos que coinciden en cada worktree que crea, incluidos los de subagentes y los de la app de escritorio. Después instala las dependencias en el worktree, o configúralo en los ajustes: este ejemplo parte de tu trabajo actual, reutiliza un único node_modules y solo hace checkout del paquete web.

   {
     "worktree": {
       "baseRef": "head",
       "symlinkDirectories": ["node_modules"],
       "sparsePaths": [".claude", "packages/web"]
     }
   }

4. Deja trabajar a las sesiones

   Mientras una sesión está aislada, Claude Code rechaza las ediciones de archivos que apuntan al checkout principal, los comandos cuyo directorio de trabajo es el checkout principal y los comandos de git redirigidos hacia él (git -C, --git-dir, GIT_DIR). No controla lo que escribe un comando de shell normal como cp, así que los permisos y el sandbox siguen importando.

5. Revisa y fusiona como cualquier rama

   Cada worktree es una rama normal. Haz commit y push desde dentro, abre un pull request y revísalo como harías con el de un compañero. Como todos los worktrees comparten .git, la rama se ve desde tu checkout principal al instante.

6. Sal y limpia

   Al salir, Claude Code revisa el worktree. Uno limpio de una sesión sin nombre se elimina automáticamente junto con su rama; una sesión con nombre pregunta antes. Si hay cambios, archivos sin seguimiento o commits nuevos, pregunta si quieres conservar o eliminar el worktree, e imprime un comando claude --worktree <name> --resume para volver más tarde.

Fuente: documentación de Claude Code, Run parallel sessions with worktrees

Ajustes de worktree en Claude Code

Todos van bajo worktree en un archivo de ajustes (~/.claude/settings.json, .claude/settings.json o .claude/settings.local.json).

Worktree de Claude Code frente a rama y a git worktree

Hacerlo a mano con git worktree

Usa git directamente cuando quieras una rama concreta que ya existe o una carpeta fuera del repositorio; worktree.baseRef no puede apuntar a una rama. Claude Code sigue compartiendo los plugins y las aprobaciones de permisos con estos worktrees.

1. Crea el worktree, inicia Claude y elimínalo al terminar

   Sustituye feature-a por el nombre de una rama nueva, o quita -b para hacer checkout de una rama que ya existe.

   git worktree add ../app-feature-a -b feature-a
   cd ../app-feature-a && claude
   git worktree list
   git worktree remove ../app-feature-a

Subagentes y sesiones en segundo plano en worktrees

• Pídele a Claude que "use worktrees para sus agentes", o añade isolation: worktree al frontmatter de un subagente personalizado en .claude/agents/, y cada subagente edita en su propio worktree temporal.
• El worktree de un subagente sin cambios se elimina cuando el subagente termina. Uno con cambios se queda hasta que una limpieza periódica pueda eliminarlo sin perder trabajo, pasados cleanupPeriodDays.
• Las sesiones en segundo plano (claude --bg) editan solo dentro de un worktree por defecto; inicia una con claude --bg --worktree o pon worktree.bgIsolation en "none".
• En la app de escritorio, activa Worktree bajo el cuadro de texto antes de iniciar una sesión.

Limpieza de worktrees y problemas comunes

• Las ejecuciones con claude -p --worktree no muestran el aviso al salir, así que dejan sus worktrees atrás. Elimínalos con git worktree remove, después de git worktree unlock si git dice que está bloqueado.
• Can only use --worktree in a git repository: ejecuta git init y haz un primer commit, o configura un hook WorktreeCreate para SVN, Perforce o Mercurial.
• Los archivos de Git LFS aparecen como archivos puntero cuando LFS se instaló con --local: ejecuta git lfs pull dentro del worktree.
• Claude Code no crea un worktree cuando .claude o .claude/worktrees es un symlink.
• Los hooks mantienen ${CLAUDE_PROJECT_DIR} apuntando al checkout principal; lee el campo cwd de la entrada del hook para obtener la ruta del worktree.
• Un worktree con base "fresh" y sin commits propios, o cuyo PR ya se fusionó, se restablece a la rama por defecto cuando lo reabres por su nombre.

Los worktrees mantienen las sesiones separadas. Crewmark las mantiene ocupadas.

Los worktrees resuelven el problema de las colisiones, pero cada sesión sigue parada hasta que escribes. Crewmark convierte una sesión de Claude Code, Codex, DeepSeek Harness u OpenCode en un empleado de IA con un rol, un objetivo y un horario, y la despierta con un heartbeat para que tome la siguiente issue de un tablero.

1. Un empleado por worktree

   Dale a cada empleado su propio worktree y su rol, por ejemplo un programador y un revisor en el mismo repositorio, como en varios agentes de Claude Code.

2. Deja que el heartbeat inicie el trabajo

   Durante su horario laboral cada empleado se despierta cada 15, 30 o 60 minutos en la misma conversación; mira cómo hacer proactivo a Claude Code.

3. Asigna issues y revisa las ramas

   Pon el trabajo en el tablero; cada empleado toma una issue, hace commit en su propia rama y te escribe cuando necesita una decisión. Lee qué es un empleado de IA.

Preguntas frecuentes sobre los worktrees de Claude Code