Llevar sesiones paralelas de Claude Code con git worktrees

Stash, rama, pull, "espera, ¿qué está pasando aquí?", quien usa Claude Code como herramienta diaria conoce el efecto. Entra un arreglo urgente mientras la rama de la funcionalidad está a medias. Se acumulan tres stashes. Un revisor manda un cambio en el PR antiguo, tienes que cambiar un momento, pero se te olvida que en el repo actual sigue habiendo una edición abierta. Los git worktrees lo resuelven poniendo cada rama en su propio directorio. Una sesión de Claude Code por directorio. Sin cambiar, sin stash, sin "¿por dónde iba?".

Este playbook enseña el montaje que llevo usando más de un mes. De cuatro a seis worktrees en paralelo es realista. Uno por tarea activa.

Paso 1: Entender qué hace un worktree

Un repo de git normal tiene exactamente un working tree. Cuando cambias de rama, cambia el contenido dentro del mismo directorio. Un worktree, en cambio, es un directorio adicional conectado al mismo almacén .git, pero con su propia rama activa. Cuatro worktrees significan cuatro directorios, cuatro ramas visibles a la vez, un único grafo de commits.

Eso ahorra espacio en disco, porque internamente git guarda los objetos una sola vez. Y hace que trabajar con Claude Code sea previsible, porque cada sesión tiene un directorio bien delimitado. Se acabaron los momentos de "¿por qué ha cambiado el código en mi otra pestaña del terminal?".

Paso 2: Decidir la estructura de directorios

Antes de crear el primer worktree, fija una estructura. Yo uso:

~/projects/
  mi-proyecto/                  # repo principal, rama main
  mi-proyecto-feat-auth/        # worktree para una funcionalidad
  mi-proyecto-fix-stripe/       # worktree para un arreglo
  mi-proyecto-pr-12/            # worktree para revisar un PR

Importante: nada de worktrees dentro del repo principal. Técnicamente funciona, pero Claude Code se vuelve loco al indexar. Uno al lado del otro queda limpio.

Paso 3: Crear el primer worktree

En el repo principal:

cd ~/projects/mi-proyecto
git worktree add ../mi-proyecto-feat-auth -b feat/auth

Eso crea el directorio nuevo y a la vez crea una rama nueva feat/auth. Si quieres trabajar sobre una rama existente porque un revisor te ha mandado algo:

git worktree add ../mi-proyecto-pr-12 origin/feat/payment-refactor

git worktree list te enseña en cualquier momento lo que tienes. Si al principio te pierdes, eso ayuda.

Paso 4: Arrancar Claude Code dentro del worktree

En cada directorio de worktree arrancas su propia sesión de Claude Code. Mi montaje: una pestaña de iTerm por worktree, con el nombre de la rama en el título. Con VS Code igual, mediante workspaces.

cd ~/projects/mi-proyecto-feat-auth
claude

Conviene saberlo: Claude Code lee el CLAUDE.md del directorio de trabajo actual. Si tu repo principal tiene un CLAUDE.md, el worktree también lo tiene, porque puede ser la misma rama o porque el fichero vino en el merge. Pero los cambios en ese fichero son específicos de la rama. Eso es una funcionalidad, no un fallo. Si quieres una instrucción específica del worktree, pon un CLAUDE.local.md en el directorio del worktree. Lo ignoras en el .gitignore y Claude Code lo carga automáticamente.

Paso 5: Variar el modelo por worktree

Aquí el patrón se vuelve realmente útil. Cada worktree puede llevar un modelo distinto. Un montaje de ejemplo que tengo ahora mismo:

• mi-proyecto/ (main, repo principal), Opus 4.7, para preguntas de arquitectura y refactors grandes
• mi-proyecto-feat-auth/, Sonnet 4.6, una funcionalidad bien delimitada de complejidad media
• mi-proyecto-fix-stripe/, Haiku 4.5, un arreglo de 30 líneas
• mi-proyecto-pr-12/, Sonnet 4.6, porque quiero entender el diff de la revisión

Eso ahorra coste y latencia a la vez, porque las respuestas de Haiku vuelven en menos de dos segundos mientras Opus se lo piensa largo en la pregunta difícil. La elección de modelo se hace por sesión al arrancar o con /model en el chat en marcha.

Paso 6: Planificar la vuelta al merge

Los worktrees no sustituyen a un buen manejo de ramas. Cuando una funcionalidad está lista, haces merge o rebase de la rama hacia main como siempre. Mi flujo:

cd ~/projects/mi-proyecto
git fetch origin
git merge --ff-only origin/main          # mantener main al dia
git merge --no-ff feat/auth              # o rebase, segun la politica del repo

Mientras exista el worktree, la rama está activa ahí y no la puedes tener activa en paralelo en el repo principal. Eso es a propósito. Git evita aquí el trabajo duplicado.

Paso 7: Borrar el worktree

Cuando la rama está fusionada y el worktree vacío:

git worktree remove ../mi-proyecto-feat-auth

Si el directorio ya no está (por ejemplo borrado con rm -rf), en el repo principal se queda colgada la entrada del worktree. git worktree prune lo limpia. Una vez por semana basta.

Paso 8: Combinar con el aislamiento por worktree de los subagents

Si usas subagents, puedes poner isolation: "worktree" en el frontmatter de un subagent. Eso es otro nivel distinto del patrón de usuario descrito aquí. El subagent se genera entonces él mismo en un worktree nuevo y efímero, hace su trabajo, y cuando termina hace merge del diff o lo descarta. Normalmente no ves esos worktrees, porque los gestiona Claude Code internamente.

Regla práctica: worktrees de usuario para tareas que duran más de una sesión (funcionalidades, revisiones). Worktrees de subagent para trabajos cortos y aislados (revisión de código, prueba de refactor). Puedes usar ambos en paralelo. Los detalles del patrón de subagents están en el playbook "Tu primer subagent en 30 minutos".

Paso 9: Trampas que me han costado tiempo

Tres cosas me pasaron en las dos primeras semanas:

Primera: los node_modules de Node son independientes por worktree. Si haces npm install en el repo principal, el worktree no tiene nada. Eso es coherente con el comportamiento de git, pero si cambias y se te olvida instalar, te salen errores raros. Solución: pnpm con node-linker=hoisted en todos los worktrees, o simplemente acordarse.

Segunda: los ficheros .env están en .gitignore en la mayoría de repos. O sea que tu worktree nuevo no tiene .env. Solución: un cp ~/projects/mi-proyecto/.env ../mi-proyecto-feat-auth/.env justo después del git worktree add. Yo lo he montado como una función de shell wta (worktree-add) que hace las dos cosas.

Tercera: si tu repo tiene submódulos, el worktree nuevo no los recibe automáticamente. git submodule update --init --recursive en el directorio nuevo lo resuelve.

Paso 10: Encajarlo limpio con los hooks de memoria

Si usas hooks de memoria o una skill propia que escribe un ID de sesión por proyecto, fíjate en que el hook reconozca bien el directorio de trabajo. El nombre de la rama más la ruta del worktree suele bastar como clave de sesión. En mi caso cada sesión de worktree acaba en el mismo almacén de memoria, pero con una etiqueta que nombra la rama. Así, al recuperar la memoria al día siguiente, todavía se ve de dónde salió cada idea.

Si tu hook no sabe hacer eso, es señal de que la lógica del hook está anticuada y solo conoce la raíz del repo. En el playbook "Reparar la desviación de memoria" pone cómo actualizarlo.

Qué sigue

Cuando el montaje de worktrees funcione, el siguiente paso con sentido son o bien los subagents (playbook "Tu primer subagent en 30 minutos") o bien, si todavía no tienes claro el patrón de git, el minimódulo "Git para IA" del nivel 1, en concreto la lección 9 sobre ramas y revisiones. Quien quiera llevar el patrón al equipo encuentra el escalón siguiente en el playbook "Claude Code en equipo, mantener CLAUDE.md entre todos".

Fuentes

• Documentación de git worktree: https://git-scm.com/docs/git-worktree
• Aislamiento por worktree de subagents: mira el recipe 3.3 Subagent basics (campo de frontmatter isolation)