Git worktrees para agentes de IA en paralelo

El desarrollo en paralelo con git worktree es la forma más limpia de ejecutar varios trabajos en un mismo repositorio sin mezclarlos. Con agentes de IA importa todavía más: si dos agentes trabajan en la misma carpeta, uno sobrescribe los cambios del otro, los tests se ejecutan contra código a medio hacer y nadie sabe qué cambio es de quién.

Este artículo explica qué son los git worktrees, cómo usarlos con agentes y cómo mantener reversible cada turno de un agente.

¿Qué es un git worktree?

Un git worktree abre una rama distinta del mismo repositorio en una carpeta separada, al mismo tiempo. Cada carpeta tiene sus propios archivos de trabajo, pero los datos de .git son compartidos. Un commit hecho en un worktree se ve desde los demás de inmediato.

Comparado con un clon:

Comandos básicos

Crea un worktree en una rama nueva:

git worktree add ../acme-web-auth -b auth-refactor

Abre un worktree a partir de una rama existente:

git worktree add ../acme-web-billing billing-v2

Lista y elimina worktrees:

git worktree list
git worktree remove ../acme-web-auth
git worktree prune

prune limpia los registros de worktrees cuyas carpetas se borraron a mano.

Desarrollo en paralelo con git worktree: un árbol por agente

La regla para agentes en paralelo es simple: da su propio worktree a todo agente que corra riesgo de conflictos.

Un ejemplo de distribución:

Tester comparte el worktree de Architect porque prueba el cambio de Architect y trabaja solo dentro de tests/. El agente de frontend trabaja en algo completamente distinto, en su propia rama.

Lo que consigues con esto:

• Los agentes nunca ven los archivos a medio escribir de los demás.
• Cada trabajo se fusiona a través de su propia rama y su propio pull request.
• Descartar un trabajo es tan fácil como borrar su rama.

Gestionar worktrees en AgentVera

Puedes gestionar los worktrees desde la línea de comandos, pero se hace difícil seguirlos a medida que se multiplican los agentes. En AgentVera, la pestaña “Worktrees” del panel derecho te permite:

1. Crear un worktree a partir de una rama nueva o existente.
2. Ver el recuento de cambios de cada worktree, cuánto va por delante o por detrás de la rama principal y su último commit.
3. Iniciar un agente directamente en un worktree.
4. Bloquear, podar y eliminar a la fuerza un worktree, y borrar su rama.

Al crear un agente nuevo, también puedes elegir un worktree como su espacio de trabajo, y el panel del agente muestra su rama en una pequeña etiqueta. Los archivos Markdown que los agentes cambian en los worktrees aparecen en el panel “Specs” como planes y documentos.

Mantén cada turno reversible

Los worktrees separan a los agentes entre sí. Pero ¿y si un agente va por mal camino dentro de su propio worktree?

La respuesta tradicional es hacer commit a menudo, pero hacer commit de cada paso de un agente ensucia el historial. Los turnos de AgentVera toman otro camino:

• Al inicio de cada turno, una instantánea de la carpeta de trabajo va a una ref oculta de git.
• Tu rama, tu índice y tu stash no se tocan.
• Se conservan los últimos 60 turnos por agente.
• Desde Turns en el menú Options del panel, ves los archivos que cambió un turno.
• Undo this turn revierte los cambios de ese turno, y también puedes deshacer el deshacer.

Así puedes dejar que un agente pruebe cosas con libertad: si no te gusta el resultado, estás a un clic del estado anterior.

Antes de fusionar

Antes de llevar el trabajo terminado de las ramas paralelas a la rama principal:

• Ejecuta los tests en cada worktree.
• Revisa los diffs; la revisión de código automática lo acelera.
• Ordena los mensajes de commit. El panel Git de AgentVera puede escribir un mensaje con el estilo de tu repositorio a partir del diff preparado, con Claude Haiku.
• Haz push de la rama y abre un pull request; la tarjeta de GitHub del panel Git muestra el pull request de la rama actual o abre uno nuevo.

Errores comunes

• Abrir la misma rama en dos worktrees. Git no lo permite, y eso es una salvaguarda.
• Dejar registros de carpetas borradas. Límpialos con git worktree prune.
• Olvidar node_modules. Cada worktree necesita sus propias dependencias instaladas.
• Tratar los turnos de los agentes como commits. Los turnos son para deshacer; sigue haciendo commit para tener un historial duradero.

Un día de ejemplo: tres agentes, dos ramas

Hagámoslo concreto con una jornada de trabajo.

Mañana: preparación

La carpeta principal tiene main en checkout. Hay dos trabajos: una reestructuración de la autenticación y una página de ajustes. Abres dos worktrees:

git worktree add ../acme-web-auth -b auth-refactor
git worktree add ../acme-web-settings -b settings-ui

Instala las dependencias en cada uno:

cd ../acme-web-auth && pnpm install
cd ../acme-web-settings && pnpm install

Architect y Tester empiezan en el worktree de auth-refactor; el agente de frontend empieza en settings-ui.

Mediodía: un turno sale mal

Mientras edita la página de ajustes, el agente de frontend también cambia el estilo de un componente compartido. Eso queda fuera de su alcance. En la lista de Turns ves los archivos que cambió el último turno, deshaces el turno y le dices al agente que no toque el componente compartido. El historial de la rama se mantiene limpio, porque deshacer no es un commit; es volver a la instantánea de la ref oculta.

Tarde: fusionar

Cuando termina el trabajo de autenticación, ejecutas los tests, compruebas la revisión y haces push de la rama. Si la página de ajustes no está terminada, su worktree sigue abierto y el agente continúa en la misma carpeta al día siguiente. Cuando cierras y vuelves a abrir la app, AgentVera devuelve a los agentes de Claude y Codex a la misma conversación a partir del historial del CLI.

Detalles del entorno a vigilar en los worktrees

Los tropiezos más comunes con worktrees paralelos tienen que ver con el entorno, no con el código:

• Choques de puertos: si ejecutas un servidor de desarrollo en dos worktrees a la vez, no dejes que ambos pidan el mismo puerto. Dales puertos distintos mediante variables de entorno.
• Archivos de entorno: los archivos que no están en git, como .env, no aparecen solos en un worktree nuevo; cópialos.
• Base de datos: si dos ramas llevan migraciones distintas, compartir una sola base de datos local puede dar problemas.

El panel “Ports” de AgentVera muestra los puertos a la escucha y qué agente inició cada uno, para que sepas qué worktree abrió qué servidor.

Copiar un agente y bifurcar la conversación

A veces quieres probar el mismo problema de dos maneras. Cuando copias un agente en AgentVera, su herramienta, cuenta, modelo, esfuerzo, rol, grupo y worktree se copian tal cual, y también puedes bifurcar el historial de la conversación (--fork-session para Claude, fork para Codex).

Combinado con los worktrees, eso te da una configuración de experimento potente: ejecuta dos agentes bifurcados de la misma conversación en dos worktrees, compara los resultados y fusiona la rama que te guste. Borrar la otra rama limpia el experimento sin dejar rastro.

Lista de comprobación

• ¿Tiene su propio worktree cada agente que corre riesgo de conflictos?
• ¿Están instaladas las dependencias en cada worktree?
• ¿Dicen los roles de los agentes en qué carpetas trabajan?
• ¿Se hicieron tests y una revisión antes de fusionar?

Conclusión

El desarrollo en paralelo con git worktree mantiene a los agentes físicamente separados, y los turnos mantienen reversibles los cambios de cada agente. Juntos son la base para trabajar con seguridad con varios agentes.

AgentVera reúne worktrees, turnos y el panel Git en una sola ventana. Léelo junto con agentes de programación en paralelo, o empieza con el plan gratuito.