Git worktree vs rama para agentes de IA en paralelo: cuál usar

La verdadera pregunta con agentes en paralelo

Un solo agente de IA en una sola carpeta nunca tiene este problema. Edita archivos, hace commit, sigue. El problema es enteramente ejecutar más de uno a la vez sobre el mismo repositorio. Cada agente necesita un sitio donde hacer cambios que los demás no estén cambiando también.

Hay tres formas de darles ese espacio, y no son iguales para el trabajo en paralelo. Cambiar de rama comparte un solo árbol de trabajo. Varios clones dan a cada agente una copia completa del repo. Los git worktrees dan a cada agente su propio árbol de trabajo sobre un mismo repositorio compartido. Vamos con ellas en ese orden.

Opción A: un árbol de trabajo, cambiar de rama

El instinto de mucha gente son las ramas. Haz una rama por tarea, y deja que cada agente trabaje en la suya. Es la idea correcta para mantener el trabajo separado en el historial, pero se rompe en cuanto quieres que los agentes se ejecuten a la vez.

La razón es que una rama no es un sitio donde trabajar, es una etiqueta sobre un commit. Sigues teniendo un solo árbol de trabajo, un solo conjunto de archivos en disco. git checkout otra-rama intercambia los archivos de esa única carpeta para que coincidan con la otra rama. Dos agentes en esa carpeta siguen compartiendo exactamente los mismos archivos, por muchas ramas que existan.

# Un árbol de trabajo. checkout intercambia sus archivos en el sitio.
git checkout -b agente-auth   # la carpeta ahora en agente-auth
# ...otro agente...
git checkout -b agente-tests  # la MISMA carpeta, ahora en agente-tests

Así que si dos agentes intentan trabajar a la vez, pasa una de dos cosas. O van por turnos, haciendo checkout, avanzando un poco, commiteando o guardando en stash, y volviendo a hacer checkout, que no es nada en paralelo, es una copia de trabajo compartida a ratos. O los dos editan la carpeta mientras está en una rama y vuelves al choque original, con la confusión añadida de ramas que ya no coinciden con lo que hay en disco.

Opción B: un clon completo por agente

La siguiente idea es dar a cada agente una copia de verdad separada: ejecuta git clone unas cuantas veces y apunta un agente a cada carpeta. Esto sí da aislamiento real. Cada carpeta tiene sus propios archivos, su propia rama, su propio todo, así que los agentes no pueden chocar.

# Una copia completa e independiente por agente
git clone git@github.com:me/app.git app-auth
git clone git@github.com:me/app.git app-tests
git clone git@github.com:me/app.git app-docs

Funciona, pero es pesado. Cada clon carga una copia completa del historial y del almacén de objetos, un remoto aparte que hacer fetch y push, y su propio espacio en disco. En un repo grande eso es mucha duplicación para lo que intentas hacer. Además ahora mantienes varias copias independientes: traer actualizaciones, mantener los remotos sincronizados y limpiarlos se multiplican por el número de agentes.

Para un par de copias de larga vida está bien. Para levantar tres o cuatro workspaces de agente de corta vida varias veces al día, clonar el repo entero cada vez es más maquinaria de la que el trabajo necesita.

Opción C: git worktrees, un solo repo compartido

Los git worktrees son el camino intermedio que encaja con los agentes en paralelo justo. Un worktree es un árbol de trabajo extra de un repositorio. Sigue habiendo un único .git compartido por todos, pero cada worktree es una carpeta separada checkouteada en su propia rama. Consigues el aislamiento de carpetas real de los clones sin duplicar el historial.

# Un repo, varios árboles de trabajo ligeros
git worktree add ../agente-auth -b agente-auth
git worktree add ../agente-tests -b agente-tests
git worktree add ../agente-docs -b agente-docs

# Limpia uno cuando su trabajo esté fusionado
git worktree remove ../agente-auth

Ahora N agentes pueden ejecutarse de verdad a la vez. Cada uno edita su propio checkout, en su propia rama, así que las ediciones solapadas son imposibles. Como comparten un solo almacén de objetos, un worktree nuevo solo cuesta los archivos checkouteados, no otra copia del repo, así que añadir un agente es barato. Y comparten un remoto y un historial, así que el fetch y el push siguen siendo simples.

Esa es toda la razón de ser de los worktrees: varios árboles de trabajo respaldados por un solo repositorio. Es el montaje que se corresponde directamente con "varios agentes, un repo, todos a la vez".

Comparativa rápida

Las tres opciones según lo que importa cuando quieres agentes ejecutándose a la vez:

Paralelismo real

• Cambiar de rama: No, un solo árbol de trabajo significa que los agentes van por turnos o chocan
• Varios clones: Sí, cada carpeta es totalmente independiente
• Worktrees: Sí, cada agente tiene su propio checkout en su propia rama

Peso y disco

• Cambiar de rama: Lo más ligero, pero no resuelve el problema
• Varios clones: Pesado, un historial completo y un remoto copiados por agente
• Worktrees: Ligero, un almacén de objetos compartido, solo los archivos checkouteados por agente

Remotos e historial

• Cambiar de rama: Uno, pero compartido de forma insegura entre agentes
• Varios clones: Uno por clon, cada uno con su fetch y su sincronización aparte
• Worktrees: Un remoto y un historial compartidos por todos los worktrees

Limpieza

• Cambiar de rama: Nada que eliminar, pero nada quedó aislado
• Varios clones: Borrar carpetas enteras, y antes desenredar cualquier estado solo local
• Worktrees: git worktree remove, un comando por workspace de agente

Cambiar de rama es la herramienta equivocada para ejecutar agentes a la vez. Varios clones funcionan pero son más pesados de lo que el trabajo necesita. Los worktrees son el encaje: aislamiento real, baratos de añadir, un solo repo que mantener.

Cuándo basta con una rama

Nada de esto significa que los worktrees sean siempre la respuesta. Si ejecutas un agente cada vez, una rama por tarea no solo está bien, es lo correcto. Haz una rama, deja que el agente trabaje, haz commit, cambia a la siguiente tarea. No hay choque porque nada más está tocando la carpeta, y consigues todas las ventajas de siempre de las ramas para organizar y revisar el historial.

Incluso con varios agentes, si solo editan archivos claramente distintos, un checkout compartido puede aguantar: las ediciones no se solapan, así que nada sobrescribe nada, y Git fusiona limpio. Los worktrees empiezan a importar en concreto cuando los agentes se ejecutan a la vez y pueden tocar los mismos archivos, o cuando quieres que dos trabajen la misma zona en ramas separadas. Tira del aislamiento cuando los choques son reales, no por defecto.

Cómo usa los worktrees CodeAgentSwarm

CodeAgentSwarm es una app de escritorio para ejecutar un enjambre de agentes CLI de IA (Claude Code, Codex CLI, opencode, Antigravity CLI) en un solo sitio, y mete la opción de worktree directamente en cada terminal, así nunca ejecutas los comandos tú mismo.

En la configuración de sesión por terminal, la fila OPTIONS tiene un interruptor Git Worktree (junto a Turbo para los agentes que lo admiten; para opencode solo aparece Git Worktree). Actívalo y esa conversación obtiene un worktree en <repoRoot>/.codeagentswarm/worktrees/<slug>/ en una nueva rama cas/<slug>, partida desde tu HEAD local. Es la Opción C de arriba, un comando por agente, hecho por ti y con un nombre consistente.

También te quita el desorden de en medio. CodeAgentSwarm añade .codeagentswarm/ a tu .gitignore para que los worktrees nunca aparezcan en git status, y es a prueba de fallos: si la carpeta no es un repo de git, el terminal se abre con normalidad. Un ajuste global puede activar los worktrees en todos los terminales, y puedes fusionar o eliminar un worktree desde Ajustes cuando el trabajo esté hecho. Consigues el paralelismo de los worktrees sin los malabares con las ramas ni la limpieza.