Git worktrees para agentes de IA: da a cada agente su propio checkout
.git. Dale a cada agente su propio worktree y dejan de pisarse, sin que tengas que clonar el repo cinco veces.
En esta guía explico el problema en concreto, qué es de verdad un git worktree, cómo crear uno a mano y cómo CodeAgentSwarm monta uno por terminal de forma automática, para que un enjambre de agentes en paralelo funcione sin más. Si quieres la vista general de ejecutar varios agentes a la vez, empieza por la introducción al enjambre de agentes CLI de IA.El problema: varios agentes, una sola copia de trabajo
Un checkout es el conjunto de archivos que hay ahora mismo en la carpeta de tu proyecto. Cuando un agente trabaja en esa carpeta, todo va bien. El lío empieza en cuanto un segundo agente trabaja en la misma carpeta a la vez. Los dos leen y escriben exactamente los mismos archivos.
Imagina que Claude Code está reescribiendo auth.ts y aún no ha hecho commit. En otro terminal, Codex CLI abre el mismo archivo, hace su propia edición y guarda. El trabajo a medias de Claude Code acaba de perderse en parte, y Codex está construyendo sobre un archivo que va a cambiar bajo sus pies. Ninguno de los dos hizo nada mal. Simplemente no pueden ser dueños los dos de una sola copia de trabajo.
Esto no es cosa de una herramienta concreta. Ejecutes Claude Code, Codex CLI, opencode u Antigravity CLI, en cuanto dos cualesquiera comparten un checkout y tocan archivos que se solapan, sus cambios sin commitear chocan.
Si tus agentes solo editan archivos distintos, un checkout está bien y no necesitas worktrees. El problema es real cuando los agentes se solapan, o cuando quieres que dos trabajen la misma zona en ramas separadas a la vez.
La solución obvia es dar a cada agente su propia carpeta. Podrías clonar el repo varias veces, pero eso es pesado y un desperdicio. Git ya trae una respuesta más ligera de fábrica: los worktrees.
¿Qué es un git worktree?
Un repositorio de git tiene exactamente un directorio .git. Ahí vive todo el historial: cada commit, cada rama, el almacén de objetos completo. Un worktree es un árbol de trabajo de ese repositorio, una carpeta con los archivos checkouteados, y un repo puede tener más de uno a la vez.
Lo importante es que todos los worktrees comparten ese único .git. Hay un solo historial, un solo conjunto de objetos, un solo remoto. Lo que cambia es la copia de trabajo: cada worktree está checkouteado en su propia rama, en su propia carpeta. Así puedes tener main checkouteado en una carpeta y feature-login en otra, una al lado de la otra, respaldadas por el mismo repositorio.
El comando para añadir uno es git worktree:
# Desde dentro de tu repo, crea un nuevo árbol de trabajo
# en ../feature-x, checkouteado en una nueva rama feature-x
git worktree add ../feature-x -b feature-xEso te da una segunda carpeta, ../feature-x, con los archivos del proyecto checkouteados en una rama feature-x nueva. Edita ahí y no toca para nada tu carpeta original. Cuando terminas, la eliminas:
# Lista los worktrees que tiene este repo
git worktree list
# Elimina uno cuando hayas terminado con él
git worktree remove ../feature-xPor qué worktrees y no clones
Podrías conseguir carpetas aisladas ejecutando git clone varias veces, pero cada clon es una copia completa: su propio .git, su historial duplicado, su remoto que mantener sincronizado y su propio espacio en disco. Los worktrees se saltan todo eso. Comparten el almacén de objetos del único repositorio, así que un worktree nuevo solo cuesta los archivos checkouteados, no otra copia del historial. Para dar a cinco agentes cinco carpetas, esa diferencia suma rápido.
Una regla que conviene saber: dos worktrees no pueden tener checkouteada la misma rama a la vez. Cada worktree necesita su propia rama. Eso es justo lo que quieres para agentes en paralelo de todas formas, una rama por agente, pero conviene saberlo antes de intentar añadir un worktree sobre una rama que ya está checkouteada en otro sitio.
A mano: un worktree por agente
Sabiendo el comando, puedes montar un enjambre aislado a mano. Dale a cada agente su propio worktree en su propia rama, y luego arranca el agente dentro de esa carpeta.
# Desde tu repo, un worktree por agente
git worktree add ../agente-auth -b agente-auth
git worktree add ../agente-tests -b agente-tests
git worktree add ../agente-docs -b agente-docs
# Luego arranca un agente en cada carpeta
cd ../agente-auth && claude
# (nuevo terminal)
cd ../agente-tests && codex
# (nuevo terminal)
cd ../agente-docs && opencodeAhora cada agente tiene su propio checkout en su propia rama. Todos pueden editar auth.ts si quieren, porque cada uno edita una copia distinta. Nada choca, y fusionas las ramas de vuelta cuando el trabajo está bien.
Esto funciona, y si solo levantas un enjambre de vez en cuando es perfectamente razonable. La fricción está en la contabilidad. Creas una carpeta y una rama por agente, recuerdas qué agente está en qué carpeta, limpias los worktrees cuando terminas y mantienes esas carpetas extra fuera de tu editor y de tu git status. Hazlo varias veces al día entre proyectos y el montaje empieza a costar más de lo que ahorra.
Cómo lo hace CodeAgentSwarm automáticamente
CodeAgentSwarm es una app de escritorio para ejecutar un enjambre de agentes CLI de IA en un solo sitio. Funciona sobre las CLIs oficiales (Claude Code, Codex CLI, opencode, Antigravity CLI), así que no es un proveedor de modelos, orquesta los agentes que ya usas. Y puede crear un worktree por terminal por ti, así consigues el aislamiento de arriba sin tocar un solo comando de git.
El interruptor Git Worktree
En la configuración de sesión por terminal hay una fila OPTIONS con un interruptor Git Worktree. Para los agentes que admiten Modo Turbo se sitúa justo al lado de Turbo; para opencode solo aparece la opción Git Worktree. Actívalo en un terminal y, al lanzarlo, ese agente arranca dentro de su propio worktree en lugar del checkout compartido.
Qué crea
Cada conversación obtiene un worktree en <repoRoot>/.codeagentswarm/worktrees/<slug>/, checkouteado en una nueva rama llamada cas/<slug> partida desde el HEAD local de tu repo. Así el agente arranca justo desde donde estás ahora, en una rama nueva, en una carpeta propia. Es el mismo montaje de git worktree add ... -b ... de arriba, hecho por ti y con un nombre consistente.
Para que esos worktrees no ensucien tu repositorio, CodeAgentSwarm añade .codeagentswarm/ al .gitignore del repo automáticamente. Las carpetas de los worktrees viven ahí debajo, así que nunca aparecen en tu git status ni acaban en un commit por accidente.
Es a prueba de fallos. Si el directorio no es un repositorio de git, o la creación del worktree falla por lo que sea, el terminal simplemente se abre en el directorio normal. Nunca acabas con un terminal que se niega a arrancar por un problema de git.
Siempre activo y limpieza
Si quieres que todos los terminales usen un worktree sin marcar la casilla cada vez, hay un ajuste global en Ajustes (alwaysUseWorktree, desactivado por defecto) que lo activa en todos. Y cuando un trabajo está hecho, no tienes que volver a la línea de comandos: desde Ajustes puedes fusionar un worktree de vuelta o eliminarlo.
Así todo el ciclo de vida, crear una rama, checkoutear una carpeta aislada, mantenerla fuera de git status, fusionar o eliminar al final, se gestiona en la app. El método manual sigue estando debajo; CodeAgentSwarm solo lo ejecuta por ti en cada terminal.
Por qué esto habilita un enjambre de agentes de verdad
El aislamiento es lo que convierte "varios terminales abiertos" en un enjambre en el que de verdad puedes confiar. En cuanto cada agente tiene su propio worktree en su propia rama, todos pueden ir a máxima velocidad, sobre partes que se solapan del código, sin un solo choque en el trabajo sin commitear. Dejas de racionar qué agente puede tocar qué archivo.
También encaja con cómo revisas el trabajo. Cada agente deja sus cambios en su propia rama cas/<slug>, así que miras cada uno como un diff autocontenido y fusionas los buenos. Nada queda enredado en una copia de trabajo compartida, así que una mala tanda en una rama nunca envenena las demás.
Los worktrees son la capa de aislamiento; el resto de CodeAgentSwarm es la capa de visibilidad encima. Sigues teniendo notificaciones de escritorio cuando un agente termina, historial buscable de todos ellos y diffs en vivo por terminal, ahora con la garantía de que los agentes no se están sobrescribiendo por debajo. Si quieres sopesar los worktrees frente a solo cambiar de rama o clonar el repo, la comparativa git worktree vs rama explica cuándo tiene sentido cada uno.
¿Nuevo en ejecutar varios agentes a la vez? Mira ejecutar varias sesiones de Claude Code para Claude en concreto, o la guía del enjambre de agentes opencode si opencode es tu agente principal. Los worktrees se aplican igual a todos.
Preguntas frecuentes
Un git worktree es un árbol de trabajo adicional de un mismo repositorio: una carpeta con archivos checkouteados en su propia rama, respaldada por el mismo .git que el original. Un repo puede tener varios worktrees a la vez, cada uno en una rama distinta, todos compartiendo un solo historial y almacén de objetos. Creas uno con git worktree add <ruta> -b <rama> y lo eliminas con git worktree remove <ruta>.
Ejecutar varios agentes en un checkout hace que lean y escriban los mismos archivos, así que sus cambios sin commitear se sobrescriben. Dale a cada agente su propio worktree en su propia rama y cada uno edita una copia aislada. Pueden trabajar la misma zona del código en paralelo sin choques, y fusionas cada rama de vuelta cuando esté lista.
Para este fin, sí, normalmente. Varios clones cargan cada uno una copia completa del historial, su propio remoto que sincronizar y su propio uso de disco. Los worktrees comparten el único almacén de objetos de un repositorio, así que un worktree nuevo solo cuesta los archivos checkouteados. Consigues el mismo aislamiento de carpetas por una fracción del peso.
Cada terminal tiene un interruptor Git Worktree en su fila OPTIONS. Actívalo y ese agente se ejecuta en un worktree en <repoRoot>/.codeagentswarm/worktrees/<slug>/, en una nueva rama cas/<slug> partida desde tu HEAD local. CodeAgentSwarm añade .codeagentswarm/ a tu .gitignore para que quede fuera del 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.
No. Si tus agentes solo editan archivos distintos, un checkout compartido funciona bien y Git gestiona los merges. Los worktrees se ganan su sitio cuando los agentes se solapan sobre los mismos archivos, o cuando quieres que dos trabajen la misma zona en ramas separadas a la vez. Ahí es donde el aislamiento total corta los choques antes de que pasen.
Activa Git Worktree por terminal en CodeAgentSwarm y cada agente tendrá su propio checkout aislado, en su propia rama, sin configuración y sin dejar nada en tu git status.
Probar CodeAgentSwarm