Git Worktrees: cómo correr múltiples agentes de IA en paralelo sin romper tu proyecto

Cuando trabajas con Claude Code (o cualquier agente de código), el flujo típico es este: abres una sesión, le das una tarea, revisas el resultado e iteras hasta terminar. Pero hay un momento incómodo en ese ciclo: ¿qué haces mientras el agente está pensando y trabajando? La mayoría de las veces, nada. Te quedas mirando la terminal.

Si revisas tu backlog, es muy probable que tengas varias tareas que no dependen entre sí. No hay ninguna razón técnica para que una tenga que terminar antes de empezar la siguiente. El problema aparece cuando intentas la solución obvia.

El problema: dos agentes, un mismo directorio

Si abres dos terminales y corres Claude Code en ambas, sí puedes trabajar en dos tareas a la vez... hasta que todo se rompe. Cuando dos agentes operan sobre el mismo directorio de trabajo, ambos leen y escriben los mismos archivos. Mientras un agente trabaja, el código cambia frente a él sin que sepa por qué ni cómo, y el resultado es un desastre de cambios pisados y estados inconsistentes.

La solución no está en Claude Code ni en el modelo que uses. Está en cómo usas Git.

Qué es un worktree (y por qué resuelve esto)

Un repositorio de Git tiene dos componentes:

1. El object store: todos tus commits, tu historial y tus ramas.
2. El working tree: los archivos que ves en disco cuando abres tu editor.

Normalmente estos dos están acoplados: un repo, un working tree. Haces checkout de una rama y tus archivos cambian para reflejarla. Solo puedes estar en una rama a la vez en un directorio.

Los Git worktrees desacoplan esto. Sigues teniendo un solo object store —un repo, un historial, un directorio .git— pero ahora con múltiples working trees: cada uno es un directorio separado en tu máquina, con una rama distinta checked out, completamente independiente a nivel de archivos.

Piénsalo así: tu repo principal es la fuente de verdad, y cada worktree es un satélite. Un checkout separado del mismo repo, en otra rama, en otra carpeta. Comparten historial y remotes, pero no comparten archivos en disco. Cada agente construye su feature sin afectar a los demás.

Manos a la obra: crear tu primer worktree

Todo se maneja desde el CLI de Git. Entra a un directorio con un repo activo y lista los worktrees existentes:

git worktree list

Si nunca has usado worktrees, solo verás tu directorio principal con main. Cada línea del listado muestra tres cosas: el directorio donde viven los archivos, el commit actual y la rama asociada.

Un detalle útil: si corres git branch, las ramas que están abiertas en otro worktree aparecen resaltadas (en la mayoría de terminales, en otro color). Así sabes de un vistazo qué ramas están "ocupadas" en algún directorio y cuáles solo existen localmente.

Convención de nombres

Antes de crear el worktree, un consejo de organización: nombra todos tus directorios de worktree empezando con el nombre del proyecto, seguido del feature. Por ejemplo:

ai-agent/                    ← repo principal (main)
ai-agent-dashboard/          ← worktree del dashboard
ai-agent-hubspot-access/     ← worktree de la integración con HubSpot
ai-agent-endpoint/           ← worktree del nuevo endpoint

Cuando hagas ls, todos los worktrees del proyecto aparecen juntos. Y cuando tengas varias terminales abiertas trabajando en features distintos, el nombre del directorio te dice exactamente qué está pasando dónde. Es una convención, no una regla: nómbralos como quieras, pero nómbralos con intención.

Crear el worktree

Desde tu repo, crea un worktree un nivel arriba del directorio actual (para que no queden anidados), con una rama nueva basada en la rama que uses como base:

git worktree add ../ai-agent-endpoint -b new-endpoint origin/staging

Desglosando el comando:

• ../ai-agent-endpoint es el directorio nuevo donde vivirán los archivos.
• -b new-endpoint crea una rama nueva para ese worktree.
• origin/staging es la rama base. Si trabajas solo con main, usa origin/main.

Git prepara el worktree, crea la rama con tracking contra la base, y deja el HEAD en el último commit de esa rama. Si vuelves a correr git worktree list, verás el nuevo worktree en la lista.

Requisito previo: los worktrees son una extensión de un repositorio existente. Si tu proyecto aún no está versionado, el paso cero es git init (o clonar tu repo remoto); sin eso, git worktree add falla con "not a git repository".

Comprueba el aislamiento tú mismo

Para convencerte de que los directorios son realmente independientes, haz una prueba rápida: entra al worktree nuevo y crea un archivo cualquiera. Si vuelves al directorio principal, ese archivo no existe ahí — cada working tree tiene sus propios archivos en disco.

Y si abres ambos directorios en tu editor de código, verás en el panel de Source Control dos estados de Git distintos para el mismo proyecto: cada worktree con su propia rama, su propio staging y sus propios cambios pendientes. Es la confirmación visual de todo lo que explicamos arriba: un solo object store, múltiples working trees.

Un flujo real con dos agentes en paralelo

Así se ve esto en la práctica con dos features simultáneos:

Terminal 1 — entras al worktree del dashboard y abres tu agente (Claude Code, Codex, el que prefieras; el flujo es idéntico). Le das una tarea de backend: integrar una API externa de datos al dashboard. Es un cambio de backend, así que sabes que no va a tocar los archivos del otro feature.

Terminal 2 — mientras el primer agente trabaja, entras al worktree de HubSpot y abres otra sesión del agente. Aquí la tarea es de frontend: agregar un checkbox de "seleccionar todo" en la UI. Como este worktree tiene su propio directorio, incluso puedes correr la app localmente desde ahí y ver los cambios de UI en vivo, sin interferencia del otro agente.

Un detalle importante: lee siempre lo que el agente te propone antes de aceptar. En este flujo es común que el agente sugiera crear una rama nueva para un cambio que tú quieres mantener dentro del feature actual. Verifica en qué rama estás y dile explícitamente que se quede en ella si eso es lo que quieres. La supervisión sigue siendo tu trabajo.

Cuando ambas sesiones terminan, un git status en cada directorio lo confirma: cambios de backend en un lado, cambios de HTML/CSS en el otro, sin tocarse entre sí. Cada rama se commitea, se pushea y se mergea por PR a staging (o a main, según tu flujo) de forma independiente.

Una advertencia honesta: si los agentes sí llegan a tocar archivos que se solapan, vas a tener que resolver conflictos de merge. Los worktrees no eliminan los conflictos; eliminan el caos de escribir sobre los mismos archivos al mismo tiempo. Elige tareas que no compartan archivos y el problema casi desaparece.

El atajo nativo: claude --worktree

Todo lo anterior es el flujo manual con el CLI de Git, y vale la pena conocerlo porque explica qué está pasando por debajo. Pero si tu agente es Claude Code, existe un atajo nativo que hace todo en un solo paso:

claude --worktree mi-feature
# o la forma corta:
claude -w mi-feature

Este comando crea el worktree, crea la rama y abre la sesión de Claude dentro del nuevo directorio, todo de una vez. Por defecto el worktree se crea en .claude/worktrees/<nombre>/ en la raíz de tu repo, sobre una rama nueva llamada worktree-<nombre> (basada en la rama remota por defecto). También puedes omitir el nombre y dejar que Claude genere uno automáticamente.

Algunos detalles útiles del soporte nativo:

• En la app de escritorio de Claude Code, cada sesión nueva obtiene su propio worktree automáticamente — el aislamiento viene de fábrica.
• Los subagentes también pueden aislarse: dentro de una sesión, Claude puede lanzar subagentes con isolation: worktree, que crean worktrees temporales para subtareas paralelas.
• Cerrar la sesión no borra el worktree. El directorio y la rama se quedan en disco a propósito, para que no pierdas trabajo sin commitear. La limpieza es tu responsabilidad (siguiente sección).
• Ubicación personalizable: si .claude/worktrees/ no te conviene (por ejemplo, porque sirves el proyecto desde un directorio específico), los hooks WorktreeCreate y WorktreeRemove permiten personalizar dónde se crean.

¿Cuándo usar cuál? El flag es ideal para sesiones rápidas y desechables donde no te importa la convención de nombres. El flujo manual con git worktree add te da control total sobre el directorio, el nombre de la rama y la rama base — útil si trabajas con staging o sigues una convención de equipo. Y si usas otro agente (Codex, etc.), el flujo manual es el camino.

Un detalle práctico que aplica a ambos flujos: los worktrees no comparten archivos no versionados. Tu node_modules, tu .env y cualquier archivo ignorado por Git no existen en el worktree nuevo — tendrás que correr npm install y copiar tus variables de entorno en cada uno.

Limpieza: eliminar worktrees y ramas

Cuando terminas (o descartas) un feature, el ciclo se cierra así:

# 1. Elimina el worktree (borra la carpeta y desregistra la referencia)
git worktree remove ../ai-agent-endpoint

# 2. Elimina la rama si ya no la necesitas
git branch -d new-endpoint

git worktree remove es la forma correcta: se niega si hay cambios sin commitear (usa --force si de verdad quieres descartarlo todo). Y git branch -d es la versión segura del borrado de ramas: Git se niega si tiene commits sin mergear (-D fuerza el borrado).

¿Y si borraste la carpeta a mano con rm -rf? Funciona, pero deja la referencia colgada en .git/worktrees/, y cuando intentes crear otro worktree con el mismo nombre, Git te va a rechazar con "missing but already registered worktree". La solución:

git worktree prune

Eso limpia todas las referencias a worktrees cuyas carpetas ya no existen. Regla práctica: git worktree remove como método principal, rm -rf + git worktree prune como plan B si ya lo borraste a mano.

Otro tropiezo común: si eliminaste el worktree pero la rama sigue viva, git worktree add -b mismo-nombre falla con "a branch named X already exists". Ahí puedes reutilizar la rama existente (omitiendo -b) o borrarla primero con git branch -D.

Patrones avanzados

1. CLAUDE.md global + CLAUDE.md por worktree

Con Claude Code tienes un CLAUDE.md en la raíz del proyecto (con Codex, un AGENTS.md). Ese archivo define contexto e instrucciones del proyecto, y como el object store es compartido, ese contexto está disponible automáticamente en cada worktree sin configuración extra. Un solo archivo beneficia a todos los agentes que tengas corriendo.

Lo interesante viene después: puedes agregar un CLAUDE.md adicional en la raíz de un worktree específico, con contexto extra para esa tarea. Contexto scoped para trabajo scoped. El agente del dashboard puede tener instrucciones sobre la API que integra, sin contaminar el contexto de los demás.

2. Agente vs. agente: el patrón más valioso

Este es, en mi opinión, el patrón más útil de los worktrees, y no tiene que ver con el paralelismo sino con la comparación: le das a dos agentes exactamente la misma tarea en dos worktrees separados, revisas ambos resultados, eliges el mejor y descartas el otro.

Es especialmente potente para decisiones de arquitectura donde existen varios enfoques válidos y quieres verlos implementados antes de comprometerte con un diseño final. En la práctica es exploración de arquitectura casi gratis: explorar dos enfoques no te cuesta el doble de tiempo, te cuesta el mismo tiempo con la mitad del costo de oportunidad.

3. tmux: sesiones persistentes por worktree

Si corres múltiples agentes con regularidad, tmux vale la pena. Te permite crear sesiones con nombre para cada worktree, hacer detach y reattach sin perder el contexto del agente, y ver todas las sesiones activas de un vistazo.

Instalación (en macOS):

brew install tmux

Crear una sesión con nombre apuntando al directorio del worktree:

tmux new-session -s hubspot -c ../ai-agent-hubspot-access

Y listar todas tus sesiones activas, con su estado (attached o detached):

tmux ls

Con esto, las sesiones de tus agentes persisten aunque cierres la terminal, y puedes revisar cualquier agente en cualquier momento. El setup final al que apunta este flujo: una sesión de tmux por worktree, cada una con su propia instancia de Claude Code, cada una con su propia tarea.

Cuándo usar worktrees (y cuándo no)

Usa un worktree cuando:

• Tienes dos o más tareas para hoy que no comparten los mismos archivos.
• La tarea es lo suficientemente riesgosa como para querer ver dos enfoques implementados antes de comprometerte con uno.

Quédate en una sola sesión cuando:

• Una sola tarea abarca todo el codebase. Ahí el paralelismo no aporta y sí complica.
• La tarea es exploratoria: deja que el agente recorra el código libremente sin fragmentar el contexto.

Proyectos relacionados

Si este flujo te engancha y quieres llevarlo más lejos, hay herramientas de la comunidad construidas justo sobre esta idea de worktrees + agentes + tmux:

• workmux — automatiza la combinación de Git worktrees con tmux: crea el worktree, levanta la sesión y lanza tu agente en un solo comando.
• worktrunk — un CLI para gestionar el ciclo de vida completo de worktrees pensado para flujos de desarrollo con agentes en paralelo.

Ambos resuelven el "pegamento" manual que vimos en la sección de tmux, así que son el paso natural cuando pasas de dos worktrees ocasionales a un flujo diario con varios agentes.

Conclusión

Los worktrees no son una feature nueva de Git ni requieren tooling adicional: son una capacidad que siempre estuvo ahí y que la era de los agentes de código volvió imprescindible. Un solo repo, múltiples directorios independientes, múltiples agentes trabajando en paralelo sin pisarse, y de regalo el patrón de comparación agente vs. agente para decisiones de arquitectura.

Y si tu agente es Claude Code, ni siquiera necesitas el flujo manual: claude --worktree hace todo en un solo comando. Si hoy tu flujo consiste en esperar mirando la terminal, este cambio —que toma cinco minutos configurar— convierte ese tiempo muerto en features avanzando en paralelo.