Git worktrees: un solo cerebro, muchos agentes trabajando en paralelo

Imagina un único repositorio con varias áreas bien diferenciadas - un frontend, un backend, algo de infraestructura, el cableado de CI/CD - y varios agentes trabajándolo al mismo tiempo, cada uno en su propia branch. Quieres que avancen en paralelo sin pisarse, y quieres una inteligencia central capaz de ver todo su trabajo a la vez: revisar el diff de un agente, hacer merge del de otro, resolver un conflicto, mantener el conjunto coherente. Las respuestas obvias fallan ambas. Los worktrees de Git son la respuesta que no falla.

El problema: un checkout solo tiene una branch

Un clon normal solo puede tener una branch en checkout a la vez. Si el agente A cambia el directorio de trabajo a su branch, los ficheros del agente B cambian bajo sus pies - has serializado a todo el mundo en un único escritorio. La solución evidente es tener N clones completos, uno por agente. Funciona, pero cada clon es su propio .git: una copia completa del historial, sus propios remotes, su propio estado de fetch. No comparten objetos y localmente no se conocen entre sí, así que mover una branch de uno a otro implica un viaje de ida y vuelta a través del remote.

Los worktrees son el camino intermedio: un solo repositorio - un .git, un almacén de objetos, un conjunto de branches - con muchos directorios de trabajo, cada uno con checkout en una branch distinta, todos vivos al mismo tiempo. Aislamiento del estado de trabajo, compartición del historial.

Qué es realmente un worktree

Piensa en un repositorio como un cerebro y un escritorio. El cerebro es .git: la base de datos de objetos, las refs, la configuración. El escritorio es el directorio de trabajo: los ficheros que de verdad editas. Un clon normal atornilla exactamente un escritorio a un cerebro. Un worktree los desacopla - un cerebro, muchos escritorios.

Cada escritorio es un directorio real en disco, con checkout en alguna branch, con su propio HEAD y su propio index (área de preparación). Pero todos comparten el mismo almacén de objetos, así que no hay historial duplicado y el coste en disco de un escritorio extra es mínimo. Una regla mantiene a todos a salvo: la misma branch no puede estar en checkout en dos worktrees a la vez. Git sencillamente se niega - y esa negativa es justo lo que impide que dos agentes corrompan una misma branch.

Cómo funciona

Toda la interfaz es un único subcomando. Desde dentro de tu repo principal añades un escritorio, lo apuntas a una branch (nueva o existente), y git crea el directorio y le hace el checkout:

# estás en el repo principal (el "worktree principal")
cd ~/work/app

# un escritorio para el agente de backend, en una branch nueva
git worktree add ../wt-backend -b feature/be-auth

# el agente de frontend, su propia branch nueva
git worktree add ../wt-frontend -b feature/fe-redesign

# el agente de infra, a partir de una branch existente
git worktree add ../wt-infra existing-infra-branch

git worktree list     # cada escritorio + la branch que sostiene
git worktree remove ../wt-backend   # limpiar al terminar
git worktree prune    # eliminar entradas administrativas obsoletas

En disco tienes ahora hermanos - el repo principal más wt-backend, wt-frontend, wt-infra - cada uno en una branch distinta. Por debajo, los escritorios secundarios no cargan con un directorio .git completo; contienen un diminuto fichero .git que apunta de vuelta al .git/worktrees/<name>/ del repo principal. Sigue habiendo un solo almacén de objetos. Una branch creada en un escritorio es visible al instante desde cualquier otro, porque solo hay un repositorio.

Por qué es el sustrato adecuado para muchos agentes

El almacén de objetos compartido es lo importante de todo esto. Como cada branch vive en una sola base de datos, un agente coordinador situado en el worktree principal puede operar sobre el trabajo de todos sin tocar un remote: git log --all lo ve todo, puede hacer diff entre las branches de dos agentes cualesquiera, cherry-pick entre ellas, merge, resolver conflictos - todo localmente, al instante.

• Ediciones paralelas y aisladas - cada agente posee un directorio, así que no hay colisiones de ficheros.
• Una branch por agente - impuesto por git; la misma branch no puede estar viva en dos escritorios.
• Barato de levantar y desmontar - los escritorios comparten objetos, así que crear o quitar uno lleva segundos.
• Un cerebro central - un solo .git significa una única fuente de verdad sobre la que el orquestador puede razonar: cada branch, cada commit, todo el historial.
• Compilaciones y pruebas independientes - cada escritorio tiene su propio node_modules, su propia salida de compilación y sus cachés, así que los agentes ejecutan sus pipelines a la vez sin estorbarse entre sí.

Ese último punto es fácil de infravalorar. Directorios de trabajo separados implican estado de compilación separado, así que un agente de frontend puede ejecutar su servidor de desarrollo mientras el agente de infra aplica Terraform en un sandbox y el agente de backend ejecuta su batería de pruebas - sin que ninguno pelee por los mismos ficheros.

Formas de trabajar

Los worktrees son un sustrato, no un método. Unos cuantos patrones encajan limpiamente con equipos reales y flotas de agentes reales.

Orquestador y trabajadores

El worktree principal es el cerebro central. Lanza un trabajador por worktree, cada uno en su propia branch. Los trabajadores hacen commit en sus branches; el orquestador integra - merge, rebase, cherry-pick entre ellas localmente - luego hace push y abre los pull requests. Este es el encaje más próximo a "una inteligencia, muchos agentes".

1. Un worktree por área (de larga duración) - wt-fe, wt-be, wt-infra, wt-cicd como escritorios semipermanentes que reflejan tus aplicaciones. Lo mejor cuando agentes o equipos encajan limpiamente con subsistemas.
2. Un worktree por tarea (efímero) - levanta un escritorio nuevo para cada feature o bug, y deséchalo al hacer merge. Lo mejor cuando el trabajo tiene forma de tarea más que de equipo.
3. Un worktree de integración - un escritorio dedicado donde el orquestador hace merge continuamente del trabajo de todos, para detectar conflictos pronto. Tu canario de "¿sigue encajando todo?".

En Claude Code esto viene de serie

Si manejas agentes con Claude Code, el patrón de worktree es nativo en lugar de algo que cableas a mano. Un subagente se puede lanzar con aislamiento por worktree - se ejecuta en su propio worktree creado automáticamente y el escritorio se limpia después, que es el patrón efímero automatizado. También hay herramientas para mover la sesión actual hacia dentro y fuera de un worktree. Así que "una inteligencia central orquestando N agentes sobre N branches" se convierte en: esta sesión es el cerebro en el worktree principal, cada agente lanzado obtiene su propio worktree aislado, y la integración sucede de vuelta en el escritorio principal.

Detalles que conviene conocer

• La misma branch en dos worktrees está bloqueada - por diseño. Dale a cada escritorio una branch distinta.
• Los artefactos de compilación son por worktree - node_modules y similares no se comparten, así que cada escritorio necesita su propia instalación. Suele ser lo que quieres para el aislamiento, pero es disco y tiempo reales.
• No anides un worktree dentro del repo - o git intentará rastrearlo como ficheros. Mantén los escritorios como hermanos (../wt-*), e ignora el patrón si alguna vez los guardas dentro.
• Usa git worktree remove, no rm -rf - borrar la carpeta a mano deja una entrada administrativa obsoleta; git worktree prune las limpia.
• Los hooks y la configuración son compartidos - cada escritorio lee el mismo .git/config y los mismos hooks. Normalmente bien, de vez en cuando sorprende.
• Los submódulos añaden fricción entre worktrees - si tu repo los usa, cuenta con configuración extra por escritorio.

El modelo mental es todo el truco: un cerebro, muchos escritorios. Deja de pensar en un repositorio como una carpeta dentro de la cual cambias de branch, y empieza a pensarlo como un único historial compartido del que cualquier cantidad de directorios de trabajo puede leer a la vez. Eso es lo que permite a una inteligencia central coordinar una flota de agentes - cada uno con confianza en su propia branch - mientras el historial que todos comparten sigue siendo la única fuente de verdad.