Git worktrees en la era de los agentes de IA: la clave para trabajar en paralelo sin volverte loco

Durante años, los worktrees fueron una de esas funcionalidades que existían en Git pero que poca gente usaba. Estaban ahí, en la documentación, esperando su momento. Y ese momento ha llegado...

La irrupción de los agentes de IA para código (herramientas como GitHub Copilot, Claude Code, Codex, Antigravity...) ha cambiado por completo cómo se trabaja con repositorios. Antes, tú eras el único que tocaba tu código local. Ahora no. Ahora puedes tener un agente refactorizando un módulo mientras tú corriges un bug crítico. O tres agentes atacando tres tareas distintas del backlog al mismo tiempo.

El problema es que Git, por diseño, solo te deja tener una rama activa a la vez en tu directorio de trabajo. Si el agente necesita la rama feature/auth y tú estás en main con cambios sin confirmar... Pues o una cosa o la otra. O haces un stash y cambias de rama, o clonas el repo entero otra vez. Ninguna de estas opciones es precisamente cómoda.

Y aquí es donde los worktrees entran en juego.

Un worktree te permite tener varias ramas del mismo repositorio abiertas en paralelo, cada una en su propia carpeta, sin clonar nada y sin interferencias. Así, cada agente de IA trabaja en su propio worktree. Tú trabajas en el tuyo. Todos comparten el mismo historial de Git sin pisarse.

Aunque no se pensó para esto, es una pieza que encaja a la perfección en el flujo de trabajo moderno con IA. Sin worktrees, lanzar varios agentes en paralelo sobre el mismo repo puede ser un caos. Con worktrees, es un flujo limpio, predecible y fácil de controlar.

Vamos a dar un buen repaso a cómo funcionan los worktrees de Git y cómo puedes utilizarlos en tu día a día.

Qué es exactamente un worktree de Git y en qué se diferencia de un clonado normal

Un worktree es un directorio de trabajo vinculado a tu repositorio Git. Ya tienes uno desde el primer momento: cuando haces git clone, Git crea automáticamente lo que se llama el worktree principal. Lo que quizás no sabías es que puedes crear más.

Con el comando git worktree add puedes asociar al mismo repositorio tantos directorios de trabajo adicionales como necesites. Cada uno apunta a una rama diferente y tiene su propio espacio de trabajo independiente. Pero todos comparten la misma base de datos de objetos Git: el mismo historial, los mismos commits, las mismas ramas.

La diferencia con un clonado adicional (que es lo que hace mucha gente) es muy grande. Cuando clonas, Git descarga toda la historia otra vez y crea una copia completamente separada. Ocupa el doble de espacio, las ramas no se sincronizan automáticamente entre ambas copias y puedes acabar con dos entornos divergentes sin que te des cuenta. Por el contrario, un worktree es ligero: no duplica nada. Solo crea un nuevo directorio con un checkout de la rama que elijas.

IMPORTANTE: esto tiene una limitación obvia que conviene tener muy clara desde el principio: no puedes tener la misma rama abierta en dos worktrees a la vez. Git lo impide para evitar conflictos. Cada rama solo puede estar activa en un worktree al mismo tiempo. Es una restricción razonable, y en la práctica raramente es un problema.

Cómo funciona git worktree por dentro y cómo organiza las ramas y directorios

Para entender cómo Git gestiona los worktrees, hay que mirar dentro de la carpeta .git de tu repositorio, que es donde está toda la información del sistema de control de código.

Cuando creas un worktree adicional, Git guarda su información en la subcarpeta .git/worktrees/<nombre>/. Dentro de esa carpeta hay varios archivos. El más importante es gitdir, que contiene la ruta al archivo .git del worktree nuevo. En ese worktree, en lugar de una carpeta .git completa, solo hay un fichero de texto plano llamado sipmplemente .git que apunta a su vez al repositorio principal. O sea, es un enlace ligero entre ambos, no una copia.

La estructura es similar a la del siguiente diagrama:

mi-repo/
├── .git/
│   ├── worktrees/
│   │   ├── feature-auth/
│   │   │   ├── gitdir
│   │   │   ├── HEAD
│   │   │   └── commondir
│   └── ...
├── src/
└── ...

../mi-repo-feature-auth/     ← el worktree
├── .git                     ← fichero de texto, apunta a mi-repo/.git
├── src/
└── ...

Cada worktree tiene su propio archivo HEAD, lo que significa que sabe en qué rama está, sin interferir con las demás. El área de preparación (staging area) también es independiente en cada worktree, así que puedes tener cambios preparados para hacer commit en uno sin que afecten al otro.

Lo que sí se comparte es el almacenamiento de objetos (object store): todos los commits, árboles y blobs del repositorio son comunes. Por eso los worktrees son tan eficientes en espacio. Cuando haces un commit en un worktree, está inmediatamente disponible en todos los demás, porque todos leen del mismo almacén.

Este diseño también explica por qué no puedes tener la misma rama en dos worktrees: como el HEAD es por worktree pero el estado de la rama es global, dos worktrees apuntando al mismo HEAD crearían una ambigüedad que Git no puede resolver de forma segura.

Vamos a verlos en acción...

Cómo crear, listar y eliminar git worktrees

El comando principal es git worktree y tiene muy pocos subcomandos, por lo que realmente no hay mucho que memorizar.

Para crear un worktree nuevo usas add, indicando la ruta del nuevo directorio y la rama que quieres tener activa en él:

git worktree add ../mi-repo-feature-auth feature/auth

Con esto Git crea el directorio ../mi-repo-feature-auth, hace un checkout de la rama feature/auth y lo enlaza al repositorio principal. Si la rama todavía no existe, puedes crearla al vuelo con -b:

git worktree add ../mi-repo-nueva-tarea -b feature/nueva-tarea

Para ver todos los worktrees activos en un repositorio:

git worktree list

La salida te muestra la ruta de cada worktree, el hash del commit en el que está y la rama activa. Limpio y directo.

No es necesario estar en el repositorio "principal": puedes ejecutar git worktree list desde cualquier worktree del mismo repositorio y te mostrará la lista completa de worktrees registrados (incluido el principal)

Cuando ya no necesitas un worktree, primero borras el directorio y luego limpias la referencia interna:

rm -rf ../mi-repo-feature-auth
git worktree prune

También puedes hacerlo en un solo paso con el comando remove, siempre que el worktree no tenga cambios sin confirmar:

git worktree remove ../mi-repo-feature-auth

Un detalle útil: puedes mover un worktree a otra ubicación sin perder nada con git worktree move. Git actualiza todos los enlaces internos automáticamente. Es un comando poco conocido pero que ahorra más de un dolor de cabeza cuando reorganizas carpetas de proyecto.

Cómo usar git worktrees para trabajar en varias ramas y pull requests en paralelo

El caso de uso más inmediato es el que todo desarrollador ha vivido: estás en medio de una feature, con cambios a medias, y llega un bug urgente en producción. Antes, la solución era hacer stash, cambiar de rama, arreglar el bug, volver, recuperar el stash y rezar para que no hubiera conflictos. Con los worktrees, la cosa se simplifica bastante.

Tienes tu rama de feature activa en tu directorio habitual. Creas un worktree para hacer el arreglo:

git worktree add ../mi-repo-hotfix main
cd ../mi-repo-hotfix
# corriges el bug, haces el commit y el push

Tu directorio original no se ha tocado. Sin stash, sin cambios de contexto, sin conflictos, sin riesgos... Cuando terminas, eliminas el worktree y sigues donde lo dejaste. ¡Magia! 🪄 Además, si ya no lo necesitas, lo borras y santas pascuas.

El mismo patrón funciona muy bien para revisar pull requests. En lugar de cambiar de rama para revisar el código de un compañero, abres su rama en un worktree separado:

git fetch origin
git worktree add ../review-pr-42 origin/feature/pr-42

Puedes ejecutar los test, revisar el comportamiento y comparar directamente con tu rama activa, todo al mismo tiempo. Es mucho más cómodo que la alternativa habitual de cambiar de rama e interrumpir tu flujo.

Para equipos que trabajan con estrategias de ramas como Gitflow, los worktrees encajan también de forma muy sencilla. Cada entorno (develop, staging, hotfix) puede tener su propio directorio permanente, siempre listo, sin necesidad de hacer checkout cada vez. Rápido, ligero y sin ocupar espacio de disco a lo tonto.

Cómo integrar agentes de IA para código usando un git worktree por agente o tarea

Este patrón de "un directorio por contexto" es exactamente el que los agentes de IA necesitan para funcionar bien.

La idea es simple: cada agente de IA trabaja en su propio worktree, sobre su propia rama. Así no hay interferencias entre agentes, ni entre el agente y tú.

Por ejemplo, tienes tres tareas pendientes: refactorizar el módulo de autenticación, añadir test a la API de pagos y actualizar las dependencias. En lugar de asignarlas a tu agente en serie, creas un worktree para cada una:

git worktree add ../agente-auth -b feature/refactor-auth
git worktree add ../agente-tests -b feature/api-tests
git worktree add ../agente-deps -b chore/update-deps

Ahora puedes apuntar un agente a cada directorio, y que cada agente trabaje de forma completamente aislada. Puedes lanzar los tres en paralelo. Cuando uno termina, revisas su rama, haces la PR y eliminas el worktree. Sin conflictos, sin mezcla accidental de cambios.

¿Están soportados los git worktrees en Claude Code, Codex, Antigravity o Github Copilot?

En general sí. Aunque siempre puedes crearlos a mano y luego abrir tu agente dentro del nuevo worktree.

Claude Code y Google Antigravity 2.0 tienen soporte nativo para trabajar con worktrees.

En el caso de Claude Code, tiene un parámetro específico -w que te permite lanzar un nuevo worktree directamente: claude -w features/auth (o la versión larga y más expresiva del parámetro: --worktree). Este comando crea un worktree bajo la carpeta .claude/worktrees/ del proyecto, y la elimina una vez se haya confirmado el código (o si sales y no hay cambios). También crea worktrees automáticamente cuando lanza subagentes en paralelo si se lo pides expresamente o si lo especificas en el Front-Matter de un agente personalizado.

En Antigravity 2.0 (no en el Antigravity "tradicional" con IDE), cuando vas a lanzar una nueva tarea con un agente puedes dejar que trabaje en el directorio local o elegir expresamente que cree un nuevo worktree para él:

Otras herramientas, como Codex o GitHub Copilot también pueden crear git worktrees de forma automática.

Con el uso de esta característica, cada instancia del agente tiene su propio contexto de Git limpio. El agente ve exactamente los ficheros de su rama, hace sus commits en ella y no "contamina" el trabajo de los demás (al menos mientras no mezcles las ramas, claro, como en cualquier flujo de trabajo normal con Git)..

Buenas prácticas con git worktree en equipos: naming, limpieza y automatización

El único punto delicado de todo esto es la limpieza. Si lanzas muchos agentes en paralelo (o abres muchos worktrees a mano), se pueden acumular unos cuantos. Por eso las buenas prácticas de naming y limpieza son más importantes de lo que parecen.

La primera buena práctica es acordar una convención de nombres consistente para los directorios de los worktrees. Una buena opción es usar el nombre de la rama como sufijo del directorio, con un prefijo que identifique el repo:

../mi-repo-feature-auth
../mi-repo-hotfix-login
../mi-repo-chore-deps

Así, con un simple ls ..  sabes inmediatamente cuáles tienes activos y a qué proyectos y ramas pertenecen.

La segunda buena práctica es no dejar worktrees huérfanos. Cuando una rama se fusiona y se elimina del remoto, el worktree local queda colgado. Ejecuta el comando git worktree prune con regularidad. O mejor aún: añádelo como paso automático en tus hooks de Git. O crea un script de limpieza de ramas, así de simple:

git fetch --prune && git worktree prune

La tercera buena práctica es tener cuidado con las herramientas de tu entorno de desarrollo. Algunos watchers de ficheros, servidores de desarrollo o herramientas de build pueden comportarse de forma inesperada si detectan múltiples directorios con el mismo package.json o configuración de proyecto. Asegúrate de que cada worktree arranca sus propios procesos en puertos distintos si es necesario.

Por último, si usas esta funcionalidad a menudo merece la pena crear algunos alias de Git que aceleren las operaciones más repetidas. Algo tan simple como git wt-add o git wt-clean te ahorra teclear lo mismo una y otra vez.

Errores típicos con git worktrees y cómo evitarlos en tu día a día

El error más común es intentar hacer checkout de una rama que ya está activa en otro worktree. Git lo bloquea con un mensaje de error bastante claro y explícito, pero puede sorprender la primera vez:

fatal: 'feature/auth' is already checked out at '../mi-repo-feature-auth'

La solución es obvia una vez sabes lo que pasa: o usas el worktree existente, o creas una rama nueva a partir de esa. No hay otra, ya que no puede haber dos carpetas a la vez apuntando a la misma rama, como ya sabes.

Otro error frecuente es borrar el directorio de un worktree directamente sin hacer git worktree prune después. Git no detecta automáticamente que el directorio ya no existe y mantiene la referencia interna. No es catastrófico, pero git worktree list empieza a mostrar entradas que apuntan a directorios inexistentes y puede generar confusión. La solución es simple: usa siempre git worktree remove cuando puedas, y ejecuta prune cuando hayas borrado a mano.

Un tercer problema aparece con proyectos que usan node_modules, entornos virtuales de Python, paquetes NuGet u otras dependencias instaladas localmente. Cada worktree necesita su propia instalación de dependencias ya que estas carpetas que no están bajo control de código no se comparten. Es el comportamiento correcto (porque cada rama, en teoría, podría tener dependencias distintas) pero es fácil olvidarlo y ejecutar código en un worktree recién creado sin haber hecho npm install o pip install antes.

Truco: si tienes la completa seguridad de que las dependencias no han cambiado, siempre puedes añadir links simbólicos a las carpetas de dependencias desde la carpeta "principal" a los diferentes worktrees. Pero mucho ojo con esto si de repente en alguno de ellos cambias las dependencias. En ese caso, elimina el enlace e instala las dependencias de manera exclusiva.

Los worktrees son una herramienta muy potente de Git, pero también bastante desconocida. Con la llegada de la era de los agentes de IA para código se han vuelto populares de repente, pero son útiles por derecho propio y conocerlos te puede simplificar el día a día a la hora de trabajar.