Git worktrees para agentes: trabajar en paralelo sin pisarse

Un git worktree es una carpeta de trabajo extra del mismo repositorio. Así cada agente de IA edita su copia y no choca con los cambios de otro.

info Definición Rápida
Un git worktree es una carpeta de trabajo adicional vinculada al mismo repositorio, con su propia rama y sus propios archivos. Cuando se usan varios agentes de IA a la vez, darle a cada uno un worktree evita que editen los mismos archivos y se pisen.

¿Qué es un git worktree?

Normalmente tienes una carpeta del proyecto con una rama activa. Para trabajar en otra rama sin perder lo que tienes a medias, la forma clásica es guardar con git stash, cambiar de rama y volver después. La otra opción es clonar el repositorio otra vez en otra carpeta. Si los conceptos de rama o commit son nuevos para ti, empieza por Git para diseñadores y ramas y pull requests; aquí solo cubrimos lo que cambia cuando quien trabaja es un agente.

Un worktree es un punto medio. Según la documentación de Git, el nuevo worktree queda vinculado al repositorio actual y comparte todo salvo los archivos propios de cada uno, como HEAD y el índice. Es decir: dos carpetas, un solo historial.

# crea la carpeta ../proyecto-login con una rama nueva llamada feature-login
git worktree add ../proyecto-login -b feature-login

# crea un worktree sobre una rama que ya existe
git worktree add ../proyecto-revision fix-registro

# lista los worktrees del repositorio
git worktree list

# borra el worktree cuando termines
git worktree remove ../proyecto-login

Dos detalles de la documentación que importan con agentes. Si ejecutas git worktree add <ruta> sin indicar rama, Git usa una rama con el nombre de la carpeta (y la crea si no existe). Y Git se niega a crear un worktree sobre una rama que ya está abierta en otro, salvo que fuerces con --force.

¿Por qué le importa a un agente?

Un agente que edita archivos escribe directamente en la carpeta donde corre. Si lanzas dos en la misma carpeta, pueden:

  • editar el mismo archivo y dejar cambios a medio aplicar,
  • correr pruebas que fallan por el trabajo del otro,
  • hacer commits mezclados, difíciles de revisar,
  • y, si uno ejecuta una limpieza, borrar lo que el otro estaba haciendo.

Con un worktree por agente, cada uno tiene sus archivos y su rama. Al terminar entrega una rama revisable y un pull request propio. Quien revisa puede aprobar uno, pedir cambios en otro y descartar el tercero sin tocar los demás (más en revisión humana de PRs de agentes).

Varias herramientas ya lo hacen por ti, según su documentación oficial:

  • Claude Code. claude --worktree feature-auth crea la carpeta .claude/worktrees/feature-auth con la rama worktree-feature-auth. Por defecto la rama parte de la rama principal del remoto, no de tu HEAD local; con el ajuste worktree.baseRef en "head" parte de tu trabajo actual. Un archivo .worktreeinclude copia al worktree nuevo archivos ignorados como .env. Un subagente puede declararse con isolation: worktree, y su worktree temporal se borra solo si no hizo cambios.
  • Codex (app). Crea worktrees administrados en $CODEX_HOME/worktrees y por defecto trabaja con HEAD desacoplado (detached), sin atarse a una rama. Conserva por defecto los 15 más recientes y no borra uno mientras su chat siga en curso.
  • Cursor. En su ventana de agentes, cada tarea que va a un worktree recibe un checkout aparte. Un archivo .cursor/worktrees.json define los comandos de preparación y, desde Cursor 3.5, la limpieza mantiene por defecto un máximo de 25 worktrees por máquina.

Para el panorama de coordinación, mira orquestación de agentes y cómo paralelizar trabajo entre agentes.

¿Qué se comparte y qué no?

Se comparteNo se comparte
Historial de commitsArchivos de estado propios (HEAD, índice)
Referencias de ramas (refs/, salvo excepciones como refs/bisect)Rama activa: cada worktree tiene la suya
Configuración del repositorio (por defecto)Dependencias instaladas (node_modules, entornos virtuales)
Remotos configuradosArchivos ignorados como .env y bases de datos locales

La última fila es la que más muerde. Un worktree nuevo es un checkout limpio: no trae dependencias ni archivos ignorados. Hay que instalar, copiar el .env (con .worktreeinclude si la herramienta lo soporta) y, si las pruebas usan una base de datos local, darle a cada worktree la suya. Cursor, además, no recomienda enlazar dependencias con enlaces simbólicos y sugiere gestores de paquetes rápidos como pnpm o uv.

¿Cómo es el ciclo de vida de un worktree de agente?

  1. Crear. Un worktree por tarea, con un nombre que diga qué hace (fix-registro, no prueba2).
  2. Preparar. Instalar dependencias, copiar variables de entorno y apuntar a una base de datos propia.
  3. Lanzar al agente dentro de esa carpeta, con una tarea acotada.
  4. Revisar. Abre un pull request de su rama y revisa solo sus archivos.
  5. Integrar o descartar. En ambos casos, el worktree y su rama dejan de hacer falta.
  6. Limpiar. git worktree remove <ruta> se niega a borrar un worktree con archivos modificados o sin seguimiento; con --force lo permite, y ese trabajo se pierde. Para los registros de worktrees cuya carpeta ya no existe, git worktree prune los elimina.

¿Cuándo NO conviene?

  • Cuando el trabajo de dos agentes depende uno del otro en tiempo real. Un worktree los separa demasiado y terminas integrando a mano.
  • Cuando el proyecto es muy grande y cada worktree necesita instalar dependencias pesadas. El disco y el tiempo de instalación se multiplican.
  • Cuando no vas a revisar las ramas resultantes. Crear diez worktrees y dejarlos sin revisar solo produce ramas huérfanas.
  • Cuando el repositorio usa submódulos. La documentación de Git advierte que su soporte en varios checkouts es incompleto y no recomienda hacer varios checkouts de un superproyecto.

Ejemplo

Ejemplo ilustrativo: tienes un producto con un formulario de registro roto y una página de precios por rediseñar. Creas dos worktrees:

git worktree add ../app-fix-registro -b fix-registro
git worktree add ../app-precios-v2 -b precios-v2

Lanzas un agente en cada carpeta. El de registro corre las pruebas del formulario en la suya; el de precios cambia componentes en la suya. Ninguno ve los cambios del otro hasta que los integras por separado. Cuando el de registro termina, abres su pull request y revisas solo sus archivos. Después de integrarlo, ejecutas git worktree remove ../app-fix-registro y la carpeta desaparece.

Errores comunes

  • Crear worktrees y no borrarlos nunca. Se acumulan carpetas viejas que confunden.
  • Suponer que el worktree trae las dependencias instaladas. No las trae; instala antes de correr pruebas.
  • Suponer que el agente parte de tu rama actual. En Claude Code parte por defecto de la rama principal del remoto: tus commits locales sin subir no aparecen.
  • Usar la misma base de datos local en todos los worktrees. Las migraciones y los datos de prueba se pisan.
  • Intentar abrir una rama que ya está en otro worktree. Git lo rechaza, y con razón.
  • Borrar la carpeta con rm -rf en vez de git worktree remove. Git conserva el registro de un worktree que ya no existe hasta que lo purgas con git worktree prune.

Fuentes

Preguntas frecuentes

¿Qué es un git worktree?
Es una carpeta de trabajo adicional vinculada al mismo repositorio, con su propia rama y sus propios archivos. Permite tener dos ramas abiertas a la vez sin clonar el repositorio otra vez.
¿Por qué los agentes de IA necesitan worktrees?
Porque si dos agentes editan la misma carpeta, sus cambios se mezclan y uno puede sobrescribir al otro. Con un worktree por agente, cada uno trabaja en su copia y los cambios se revisan por separado.
¿Puedo usar la misma rama en dos worktrees?
Por defecto, no. Git se niega a crear un worktree sobre una rama que ya está abierta en otro, salvo que fuerces con –force. Lo habitual es crear una rama nueva para cada worktree.
¿Qué comparten los worktrees y qué no?
Comparten el historial, la configuración y las referencias de ramas. No comparten archivos de estado propios como HEAD o el índice, ni las dependencias instaladas ni los archivos ignorados como .env.
¿Qué herramientas de IA usan worktrees?
Según su documentación, Claude Code (con la opción –worktree y el aislamiento de subagentes), la app de Codex y Cursor pueden ejecutar cada tarea de un agente en su propio worktree.