¿Qué es un git worktree y cómo se usa con agentes?

¿Qué se rompe cuando dos agentes trabajan en el mismo directorio?

Hoy en día solemos ejecutar los agentes de programación en paralelo: mientras una sesión escribe una función nueva, otra corrige un error, y los subagentes cambian a la vez archivos distintos. Si todos trabajan en el mismo directorio, comparten los mismos archivos, la misma rama y el mismo index de git. En el repositorio donde desarrollamos diffox lo pagamos varias veces. De cada caso salió una regla:

• Un commit a secas se llevó también el trabajo de otro agente. git commit hace commit de todo lo que hay en el index, incluidos los archivos que otro agente del mismo directorio ha preparado. Nuestra regla: los agentes que trabajan en paralelo solo hacen commit de sus propios archivos (git commit --only <rutas>).
• Un git checkout -b cambió la rama de otra sesión. La shell del agente vuelve al directorio inicial en cada comando, y una vez un comando de git sin ruta cambió la rama de una sesión paralela. Nuestra regla: cada comando de git indica la ruta de forma explícita (git -C <ruta absoluta>).
• Una sesión planificó cambios en un directorio que cambió de rama 3 veces en 40 minutos. Por eso existe el hook de inicio de sesión que contamos en el artículo sobre hooks.
• Nuestro script de limpieza cometió el mismo error. El script que limpia las ramas fusionadas pasaba a dev cada directorio limpio que encontraba. Pero un directorio limpio puede ser de otra sesión que todavía no ha empezado a escribir; el script le cambió la rama a esa sesión. Ahora solo mueve un directorio que está en dev, en main o en una rama cuyo pull request ya se fusionó.

Lo que tienen en común es un único directorio. Para eso existe el worktree: da a cada agente su propio directorio, su propia rama y su propio index. Pero, como verás más abajo, no lo separa todo. El ajuste isolation: worktree de Claude Code lo explicamos en el artículo sobre subagentes. Este artículo se fija en el repositorio que comparten los agentes.

¿Qué es un git worktree?

Según la documentación de git, un repositorio puede tener varios directorios de trabajo (working trees), así que puedes tener más de una rama abierta a la vez. El directorio que obtienes con git clone es el worktree principal. Los que abres con git worktree add son worktrees vinculados (linked worktrees).

Un worktree vinculado lo comparte todo con el repositorio, salvo unos pocos archivos propios como HEAD y el index. El historial de commits se guarda una sola vez; cada worktree solo lleva su propia copia de los archivos. Casi todo el trabajo lo hacen estos comandos:

git worktree add -b busqueda ../proyecto-busqueda   # directorio nuevo, rama nueva
git worktree list                                   # todos los worktrees
git worktree remove ../proyecto-busqueda            # lo quita si está limpio
git worktree prune                                  # limpia el registro de los worktrees cuyo directorio se borró a mano

Git evita algunos errores por su cuenta. Una rama solo puede estar abierta en un worktree a la vez: por defecto, add rechaza una rama que ya está abierta en otro worktree. Y remove solo quita worktrees limpios; para borrar uno con cambios sin commit o con archivos sin seguimiento hace falta --force.

La diferencia entre worktree y rama. Una rama es un nombre que apunta a un commit. Un worktree es un directorio en el que están abiertos los archivos de una rama. Si cambias de rama en un único directorio, los archivos cambian para todos los que trabajan en él. Con worktrees, cada agente se queda en su propio directorio y en su propia rama. Una nota: la propia documentación de git todavía considera experimental tener varios checkouts y dice que el soporte de submódulos está incompleto.

¿Cómo se abre un worktree en las herramientas de programación?

Las cinco herramientas pueden abrir un worktree por sí mismas; en Gemini CLI la función es experimental y se activa en los ajustes. Se diferencian en dónde se abre el worktree, de qué commit parte, si trae o no los archivos que git ignora (como .env) y cuándo se borra.

Fuente: la documentación de worktrees de cada herramienta, 18 de octubre de 2026. «La documentación no lo dice»: en la página que leímos ese día no encontramos ninguna frase sobre este punto. La fila de Codex corresponde a Codex en la aplicación de escritorio de ChatGPT, que es la que describe la página. La limpieza de Cursor está descrita para la versión 3.5 y posteriores. La aplicación de GitHub Copilot también abre un worktree y una rama aparte para cada sesión.

La diferencia más importante está en el punto de partida. Por defecto, Claude Code parte de la rama por defecto del repositorio remoto; los commits a los que aún no has hecho push no están en el nuevo worktree. Copilot CLI, en cambio, parte del HEAD del checkout en el que estás. Codex lleva al nuevo worktree incluso los cambios sin commit de la rama que eliges. Elige este ajuste a conciencia, según lo que el agente necesite ver.

Los archivos que git ignora no llegan al nuevo worktree. Para eso, Claude Code y Codex leen un archivo con el mismo nombre: .worktreeinclude, en la raíz del repositorio. Se escribe con la sintaxis de .gitignore y solo copia archivos que git ignora. En Cursor hacen lo mismo los comandos de instalación de .cursor/worktrees.json; el ejemplo de la documentación copia .env con cp.

Con las dependencias, dos herramientas aconsejan cosas distintas. Cursor no recomienda traer las dependencias al worktree con enlaces simbólicos, porque puede dar problemas en el worktree principal. Claude Code, en cambio, puede traer con enlaces simbólicos directorios grandes como node_modules a cada worktree con el ajuste worktree.symlinkDirectories.

También hay comandos listos para trabajar en paralelo. La skill /batch de Claude Code reparte un cambio grande entre 5 y 30 subagentes, cada uno en su propio worktree. El comando /best-of-n de Cursor ejecuta la misma tarea en varios modelos y da a cada ejecución su propio worktree. Los equipos de agentes (agent teams) de Claude Code, en cambio, no separan a sus miembros en worktrees; la documentación te pide repartir el trabajo para que cada miembro se encargue de archivos distintos.

El 18 de junio de 2026, Google dejó de dar servicio en Gemini CLI a los usuarios gratuitos y a los suscriptores de Google AI Pro y Ultra, y los dirigió a Antigravity CLI; con una clave de API de pago o una licencia de empresa puedes seguir usando Gemini CLI. El 28 de octubre de 2026 leímos la documentación de Antigravity. Según su página de subagentes, el agente principal puede darle a un subagente que lanza su propio worktree de Git; cuando el subagente se termina, ese worktree se borra solo. La documentación no dice de qué commit parte el worktree ni si trae archivos como .env. La aplicación de escritorio puede abrir una conversación nueva directamente en su propio worktree; en la CLI no encontramos ninguna opción que lo haga.

¿Qué separa un worktree y qué no?

Es fácil pensar en un worktree como un sandbox completo. Pero git solo le da a cada worktree unas pocas cosas propias. El resto es común, y de una parte git ni siquiera se ocupa:

La configuración y la ruta de los hooks son comunes. Según git, el archivo de configuración del repositorio es común a todos los worktrees por defecto. En nuestro repositorio, la ubicación de los hooks de git también está escrita en ese archivo (core.hooksPath), como una sola ruta absoluta. Por eso el hook pre-push, que se ejecuta antes de un push, corre desde la copia del worktree principal y no desde la copia de la rama de la que haces push. El 24 de agosto de 2026 añadimos una regla nueva a este hook en una rama de un worktree, y sus 11 tests pasaron. Pero un push desde ese mismo worktree pasó igualmente, porque el worktree principal tenía la versión antigua. Lo mismo vale para otros ajustes, como la identidad (user.email); para tener ajustes propios en cada worktree hay que activar extensions.worktreeConfig en git.

Los permisos de las propias herramientas también pueden ser comunes. En Claude Code, una aprobación «Yes, and don’t ask again» que das en un worktree se escribe en el archivo .claude/settings.local.json del worktree principal y vale en todos los worktrees. En Copilot CLI, los worktrees vinculados también comparten los permisos del repositorio principal.

Las ramas y el stash son comunes. Según git, todas las referencias que empiezan por refs/ son comunes a los worktrees, y el último stash se guarda en refs/stash. Un git stash pop sin nombre de stash toma el último. Si se juntan estas frases de la documentación de git, sale esto: un git stash pop en un worktree toma el último stash aunque lo haya dejado un agente en otro worktree. En un repositorio donde trabajan agentes en paralelo, un commit temporal es más seguro que un stash.

Lo que está fuera de git no se separa en absoluto. Una base de datos, un puerto, una caché o un directorio de datos ignorado no saben nada de los worktrees. En nuestro repositorio enlazamos un directorio grande de mediciones (.runs) a cada worktree con un enlace simbólico, porque ahí están los resultados de mediciones de pago y no deben perderse al borrar un worktree. El patrón .runs/ del .gitignore solo coincide con directorios, así que no ignoró ese enlace. El 21 de agosto de 2026, git status lo mostraba en cada worktree como archivo sin seguimiento; estaba a un git add -A de entrar en un commit. Nuestros tests de base de datos también usan una base de datos de prueba común. Para que los tests de dos worktrees no se ejecuten a la vez, mantenemos un directorio de bloqueo.

¿Por qué no basta con comprobar al abrir la sesión?

Mirar el estado del directorio al abrir una sesión sirve, pero solo para ese momento. En nuestro repositorio, el hook de inicio de sesión le dice a una sesión que se abre en un dev limpio: «basta con una rama, no hace falta un worktree». Si se abren dos sesiones en el mismo dev limpio, las dos reciben esa respuesta y las dos crean una rama en el mismo directorio. Cuando la segunda pasa a su rama nueva, también cambia la rama en la que trabaja la primera.

Por eso un segundo hook, que se ejecuta antes de cada edición, compara la rama y el commit con lo último que se le dijo a la sesión. Los detalles están en el artículo sobre hooks; lo que queremos añadir aquí es qué se compara. Lo primero que se le ocurre a uno es el número de archivos sin commit. Pero el 12 de septiembre de 2026 vimos que una sola edición hecha por la propia sesión hace que un directorio limpio parezca sucio. Un aviso que se fija en eso confunde el trabajo del propio agente con el de otro. Por eso el hook solo mira la rama y el commit que hay debajo, y avisa sin detener la acción.

El hook no puede saber quién hizo el cambio, y no intenta adivinarlo. La sesión que crea su propia rama también recibe un aviso, una vez; entiende que el cambio es suyo y sigue.

Claude Code, además, ejecuta sus propias comprobaciones para una sesión aislada en un worktree. Según su documentación, rechaza las ediciones que apuntan a una ruta del checkout principal y los comandos que dirigen git al checkout principal. La documentación también deja claro el límite: estas comprobaciones no siguen en qué archivos escribe un comando de shell. Un comando que escribe en el checkout principal con cp o con una redirección no queda atrapado por ellas; según la documentación, ese comando se trata según tus ajustes de permisos y de sandbox. Es decir, lo que limita dónde puede escribir un agente no es el worktree, sino esos ajustes.

¿Por qué se acumulan los worktrees y cómo se limpian?

Abrir un worktree es un solo comando; cerrarlo, en cambio, se olvida a menudo. Como contamos en el artículo sobre subagentes, el 27 de agosto de 2026 se habían acumulado 41 worktrees en nuestro repositorio, y 37 venían de una sola ronda de revisión. El desorden no lo crean las personas, sino los flujos de trabajo. Ese día escribimos un script de limpieza. El 18 de octubre de 2026 volvimos a contar:

Ninguno de los 34 worktrees con la rama fusionada tenía cambios sin commit. Justo ese tipo de worktree es el que borra nuestro script de limpieza. Pero el script no se ejecuta solo; el hook de inicio de sesión solo sugiere ejecutarlo, y hasta que alguien lo hace, todos siguen ahí. En total, 5 worktrees estaban en el directorio de Codex (~/.codex/worktrees) y los otros 61, en .claude/worktrees/. Según la fecha de creación del directorio que git guarda para cada worktree, 28 de los que seguían ahí se habían abierto en un solo día, el 15 de octubre. El borrador de este artículo también se escribió en un worktree abierto el 18 de octubre de 2026.

Git no puede decir si una rama se fusionó. Nuestro repositorio fusiona los pull requests con squash, y el squash reescribe los commits. Por eso una rama fusionada ni es antecesora de dev ni coincide commit a commit. Miramos una rama pocos minutos después del merge: merge-base --is-ancestor dijo «no fusionada» y git cherry, «faltan 2 commits»; las dos respuestas eran falsas. Otra rama, con todo su contenido ya en dev, aparecía con «36 commits por delante». El único sitio que lo sabe es el pull request. Por eso nuestro script de limpieza pregunta a GitHub y solo borra los worktrees limpios cuyo pull request se fusionó.

El propio número puede engañar. Un worktree cuyo directorio se borró a mano sigue en la lista, marcado como prunable, hasta que se ejecuta git worktree prune. Al principio, nuestro hook de inicio de sesión contaba todas las líneas juntas. El 8 de septiembre de 2026 dijo 26 worktrees y, unos comandos después, git worktree list mostró 7. Ahora cuenta por separado los vivos y los que se pueden borrar, y sugiere el script de limpieza cuando hay más de 4 worktrees vivos o una sola entrada que se puede borrar.

La limpieza de cada herramienta también es distinta. Codex guarda por defecto sus últimos 15 worktrees. Cursor guarda por defecto 25 worktrees por máquina y, según su documentación, también considera borrables los worktrees abiertos con git worktree add. Claude Code barre los worktrees de subagentes y de sesiones en segundo plano, pero deja los que todavía tienen trabajo. Gemini CLI, en cambio, te deja la limpieza a ti. Si usas varias herramientas en el mismo repositorio, ten claro cuál borra qué.

¿Qué hay que tener en cuenta al ejecutar agentes en paralelo?

De cada error de arriba salió un punto. Todos juntos quedan así:

• No todos los agentes necesitan un worktree. Un worktree es para cuando dos trabajos quieren el mismo repositorio a la vez en commits distintos. Si una sola sesión trabaja en un dev limpio, basta con una rama. Cada worktree innecesario es un directorio más que habrá que limpiar después.
• No te olvides de la instalación. Un worktree nuevo es un checkout limpio: no tiene dependencias, ni entorno virtual, ni .env. La documentación de Claude Code y la de Gemini CLI también te piden preparar el entorno en cada worktree nuevo. En nuestro repositorio, cada worktree instala su propio entorno antes de su primera ejecución de tests.
• Reparte el trabajo por archivos. En nuestro repositorio, las tareas que se ejecutaban a la vez tenían archivos distintos, cada commit se hizo con --only y las ejecuciones de tests esperaban su turno con el bloqueo común.
• El paralelismo no sale gratis. Según la documentación de Claude Code, ejecutar varias sesiones o subagentes a la vez multiplica el consumo de tokens.

Al final, el trabajo de los agentes en paralelo llega a la misma rama en forma de pull requests, y esa rama avanza con cada merge. Cuando diffox revisa un pull request, mide el cambio desde el punto en que la rama se separó de la rama base (la merge base); es el cambio que GitHub muestra en el pull request. También lee la versión anterior de los archivos en ese mismo punto. Así, si el trabajo de otro agente se fusionó después en la rama base, no se mezcla en esta revisión.