Cómo usar Git Worktrees con agentes de programación

10 de Agosto del 202620 minGit, Worktrees, Agentes IA, Productividad

Respuesta corta (60 segundos): Git worktrees es la herramienta nativa de Git (existe desde 2015, Git 2.5) que te permite tener varios directorios de trabajo sobre el mismo repositorio, cada uno con su propia branch checkeada. Resuelve el problema de pisarse que aparece cuando dos o más agentes de programación trabajan en paralelo: cada agente tiene su propio working tree, index y HEAD, sin pisar archivos staged ni romper el dev server del otro. El setup toma 15 minutos: directorio un nivel arriba del repo principal, convención de nombres agent/<rol>/<descripcion> para las branches, alias de bash, y verificar que .worktrees/ está en .gitignore. Usalo siempre que tengas 2+ agentes en paralelo. No lo uses para un typo de una línea ni cuando necesites ambientes totalmente aislados (eso es un clone o un container).

Trabajar con varios agentes de programación al mismo tiempo sobre el mismo repositorio tiene un problema que aparece el día uno: todos comparten el mismo directorio de trabajo. El agente que está arreglando un bug modifica package.json, el que está refactorizando crea un archivo nuevo en src/, el que está escribiendo tests borra un fixture… y los tres se pisan entre sí y con tu propio trabajo.

Git tiene una herramienta específica para este escenario y la mayoría de la gente no la conoce bien: worktrees. No es nueva (existe desde Git 2.5, 2015) y es la forma correcta de hacer que múltiples agentes trabajen en paralelo sobre el mismo repo sin pisarse.

Este post es la guía que armé después de tres meses usando worktrees con agentes de programación en producción. No es teoría: son los comandos exactos que corro, la convención de nombres que funciona, los errores que ya cometí y cómo los evito.

El problema real: por qué los agentes chocan en una sola rama

Cuando tenés un solo working directory compartido, los agentes inevitablemente hacen esto:

• Se pisan archivos staged: el agente A deja 5 archivos en el index, el agente B hace git add de archivos distintos, y al hacer commit se mezclan cambios no relacionados en un solo commit.
• Rompen el build del otro: el agente A levanta un dev server en el puerto 3000, el agente B intenta levantarlo también y uno de los dos crashea.
• Pisan el branch local: si los dos agentes corren git checkout para trabajar en su propia branch, cada switch mueve archivos que el otro está editando.
• Tiran trabajo a la basura: el agente A tiene cambios sin commit, el agente B corre git stash o un git reset y los pierde.

Worktrees resuelven esto en seco: cada agente tiene su propio directorio, con su propio working tree, su propio index y su propio HEAD. Comparten el .git (refs, objetos, config) y nada más.

Qué es un worktree en 60 segundos

Un worktree es un segundo directorio de trabajo que comparte el mismo repositorio Git con el directorio principal.

Tres cosas que comparten todos los worktrees del mismo repo:

1. Los objetos y refs (el historial, las branches, los tags) viven en un solo .git.
2. La config local (user.name, user.email, alias, etc.) se hereda del repo principal.
3. Los remotos (origin, upstream) son los mismos.

Y tres cosas que no comparten:

1. El working directory (cada uno tiene su propia copia de los archivos).
2. El index (el staging area es independiente por worktree).
3. El HEAD y la branch checkeada (cada worktree tiene la suya).

Eso es todo. No hay magia. Es Git siendo Git: el modelo de datos ya soporta múltiples working trees desde hace más de una década; el comando git worktree solo expone esa capacidad.

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

Usá worktrees cuando:

• Tenés varios agentes (o vos + agentes) trabajando en paralelo sobre el mismo repo.
• Querés tener tu propio branch activo mientras un agente trabaja en otro.
• Necesitás comparar dos branches lado a lado sin hacer stash/checkout todo el tiempo.

NO uses worktrees cuando:

• Trabajás solo y nunca tenés dos branches activos a la vez (no aporta nada).
• Tu repo es enorme (>5 GB) y cada worktree duplica el working directory completo — el costo de disco se vuelve real.
• Necesitás procesos de dev server pesados por worktree (Next.js + watch + 3 worktrees = 3 GB de RAM fácil).
• Estás haciendo un release y querés un ambiente totalmente aislado — para eso es mejor un clone separado o un container.

Setup base: convenciones y comandos seguros

Antes de lanzar el primer agente con worktree, conviene fijar dos cosas: dónde van a vivir los worktrees y cómo se llaman las branches.

Dónde crear los worktrees

Los worktrees no pueden anidarse, así que la convención que uso es un nivel arriba del repo principal:

~

# Asumiendo que tu repo principal está en ~/projects/mi-app
~/projects/
├── mi-app/                     # repo principal (branch: main o develop)
├── mi-app.agent-bugfix/        # worktree del agente de bugfix
├── mi-app.agent-refactor/      # worktree del agente de refactor
└── mi-app.agent-docs/          # worktree del agente de docs

La razón es simple: el path del worktree aparece en mensajes de error de Git, en logs de CI, y en tu prompt. Si tenés un prefijo claro (mi-app.agent-*), de un vistazo sabés qué es qué.

Si ya tenés una estructura distinta (por ejemplo, todos los worktrees dentro de ~/worktrees/), mantenela. La consistencia con tu propio setup vale más que la convención que te sugiero.

Naming convention para branches de agentes

La convención que mejor me funcionó es tres segmentos separados por /:

~

agent/<rol>/<descripcion-corta-en-kebab>

# Ejemplos reales
agent/bugfix/typo-readme
agent/bugfix/login-redirect-loop
agent/refactor/extract-pdf-parser
agent/refactor/migrate-to-pino-logger
agent/feature/add-csv-export
agent/docs/api-reference-v2
agent/test/integration-coverage-70pct

Tres reglas que vale la pena respetar:

1. Empezá siempre con agent/ — un git branch -a | grep agent/ te lista todo lo que está haciendo cualquier agente, sin confundirlas con tus branches manuales.
2. Segundo segmento = rol del agente — bugfix, refactor, feature, test, docs, chore. Si sumás nuevos roles (por ejemplo, agent/security/audit-deps) los mantenés consistentes.
3. Tercer segmento = descripción concreta — typo-readme, no fix-1. Si el agente no puede resumir su trabajo en una frase corta, probablemente no entendió bien el ticket.

Verificá que .worktrees/ (o equivalente) está ignorado

Si decidís guardar los worktrees dentro del repo (no recomendado, pero válido), chequeá que la carpeta esté en .gitignore antes de crear nada:

~

# Si vas a usar .worktrees/ adentro del repo
echo ".worktrees/" >> .gitignore
git add .gitignore
git commit -m "chore: ignore .worktrees/ directory"

# Verificá que está ignorado
git check-ignore -v .worktrees/
# Salida esperada: .gitignore:NN:.worktrees/	.worktrees/

Si esto falla, Git va a commitear todo el contenido de tu worktree al repo. Es el error más caro que podés cometer con worktrees y es 100% evitable.

Estrategia de ramas para N agentes en paralelo

Una vez que tenés la convención, la pregunta real es cómo coordinás N agentes que están trabajando al mismo tiempo. Hay dos modelos.

Modelo 1: una branch por agente, sin coordinación

Cada agente trabaja completamente aislado en su branch. Al final, cada uno abre su PR y vos (o un merge bot) los mergea uno por uno.

~

# Setup inicial (una sola vez)
cd ~/projects/mi-app

# Agente 1 — bugfix
git worktree add ../mi-app.agent-bugfix -b agent/bugfix/typo-readme

# Agente 2 — refactor
git worktree add ../mi-app.agent-refactor -b agent/refactor/extract-pdf-parser

# Agente 3 — feature
git worktree add ../mi-app.agent-feature -b agent/feature/add-csv-export

Cuándo funciona: los tres agentes tocan archivos disjuntos o casi disjuntos (bugfix en README.md, refactor en src/parser/, feature en src/exports/). Los PRs mergean limpios.

Cuándo se rompe: los tres tocan package.json (cada uno suma una dep), los tres modifican src/index.ts (por imports), o hay un lockfile que cambia con cualquier commit. Ahí el merge del segundo y tercer PR se va a conflicto.

Modelo 2: base común + branches derivadas

Para features más grandes, conviene partir de una branch base que ya tenga los cimientos, y que cada agente derive la suya:

~

# 1. Crear branch base (vos o un agente senior)
git checkout main
git pull
git checkout -b feature/export-pipeline
git push -u origin feature/export-pipeline

# 2. Cada agente parte de la base
git worktree add ../mi-app.agent-export-csv -b agent/feature/export-csv feature/export-pipeline
git worktree add ../mi-app.agent-export-pdf -b agent/feature/export-pdf feature/export-pipeline
git worktree add ../mi-app.agent-export-tests -b agent/test/export-coverage feature/export-pipeline

Ventaja: los tres agentes comparten el código base que ya está mergeado, y solo modifican la parte específica de su tarea. Los conflictos se reducen a la zona donde realmente están trabajando.

Costo: tenés que mantener la branch base actualizada mientras los agentes trabajan. Si los agentes demoran varios días, mergear main → feature/export-pipeline cada mañana antes de que arranquen evita sorpresas.

¿Cuántos agentes en paralelo es razonable?

Mi regla empírica:

El límite real no es Git (que aguanta bien), es tu máquina: cada worktree puede tener su propio dev server, su propio watcher, su propio IDE. Tres Next.js en watch mode ya son 3-4 GB de RAM.

Workflow diario del agente: los 7 comandos que ejecutás

Una vez que tenés la estructura armada, el ciclo de vida de un worktree es siempre el mismo. Estos son los siete comandos que un agente (o vos) ejecuta de principio a fin.

1. Crear el worktree

~

# Desde el repo principal
cd ~/projects/mi-app
git fetch origin

# Crear worktree con branch nueva
git worktree add ../mi-app.agent-refactor -b agent/refactor/extract-pdf-parser

# Moverse al worktree
cd ../mi-app.agent-refactor

2. Trabajar dentro del worktree

Todo lo que el agente haga adentro es local al worktree. El repo principal no se entera hasta que haya un push.

~

# El agente trabaja normal
git status
git diff
# ... edita archivos ...
git add -p          # o git add <archivos>
git commit -m "refactor: extract PDF parser into src/parser/pdf.ts"

# Si necesita instalar deps (en ese worktree)
pnpm install        # solo afecta a este worktree

3. Mantenerse actualizado con main

Si la branch base (main o feature/...) avanzó mientras el agente trabajaba, conviene rebasear antes de abrir el PR:

~

# Adentro del worktree del agente
git fetch origin
git rebase origin/main        # si la base es main
# o
git rebase origin/feature/export-pipeline

# Si hay conflictos, resolver y continuar
git status
# ... resolver archivos ...
git add <archivos-resueltos>
git rebase --continue

4. Pushear y abrir el PR

~

# Adentro del worktree del agente
git push -u origin agent/refactor/extract-pdf-parser

# Abrir PR (manual, con gh, o desde la UI)
gh pr create --base main \
  --title "refactor: extract PDF parser" \
  --body "Extrae la lógica de parsing de PDF a src/parser/pdf.ts. Cierra #234."

5. Esperar review y mergear

Desde el repo principal (o la UI), mergeás el PR. GitHub/GitLab mergean la branch en main (o la base) y eliminan la branch remota automáticamente si lo configuraste así.

6. Limpiar el worktree local

Una vez mergeado, volvés al repo principal y removés el worktree:

~

# Desde el repo principal
cd ~/projects/mi-app

# Verificar que el PR ya está mergeado
git log --oneline -1 origin/main

# Remover el worktree (falla si hay cambios sin commit)
git worktree remove ../mi-app.agent-refactor

# Borrar la branch local que ya no existe en remoto
git branch -d agent/refactor/extract-pdf-parser

# Si la branch quedó zombie en remoto
git push origin --delete agent/refactor/extract-pdf-parser

7. Listar y mantener limpio

Periódicamente conviene revisar qué worktrees siguen vivos y podar referencias obsoletas:

~

# Ver todos los worktrees activos
git worktree list

# Salida esperada:
# /home/user/projects/mi-app                abc1234 [main]
# /home/user/projects/mi-app.agent-refactor def5678 [agent/refactor/extract-pdf-parser]
# /home/user/projects/mi-app.agent-bugfix   ghi9012 [agent/bugfix/login-redirect]

# Limpiar referencias a worktrees cuyos directorios ya no existen
git worktree prune

# Verificar que la lista está limpia
git worktree list

Revisión de cambios entre agentes

Una de las ventajas menos obvias de los worktrees es que podés diffear lo que hizo un agente contra lo que estás haciendo vos, sin hacer checkout. Esto vale oro cuando tenés que decidir si el PR de un agente entra en lo que vos estás construyendo.

Diff entre tu branch actual y la de un agente

~

# Desde tu repo principal (branch: main o la tuya)
git diff main..agent/refactor/extract-pdf-parser
git diff main..agent/refactor/extract-pdf-parser --stat

# Ver archivos específicos
git diff main..agent/refactor/extract-pdf-parser -- src/parser/pdf.ts

Diff entre dos branches de agentes

Cuando dos agentes trabajaron en paralelo y querés ver qué hizo cada uno:

~

# Ver qué cambió el agente A pero no el agente B
git diff agent/refactor/extract-pdf-parser..agent/feature/csv-export

# Ver la intersección (archivos que tocaron ambos — candidatos a conflicto)
git diff --name-only agent/refactor/extract-pdf-parser agent/feature/csv-export \
  | xargs -I {} sh -c 'git log --oneline agent/refactor/extract-pdf-parser agent/feature/csv-export -- {}'

Traer cambios de un agente a tu worktree

Si querés probar lo que hizo un agente antes de aprobar el PR, podés mergear su branch en tu worktree sin tocar el resto:

~

# Desde TU worktree (no el principal)
cd ~/projects/mi-app.agent-feature

# Traer la branch del agente
git fetch origin
git merge origin/agent/refactor/extract-pdf-parser --no-ff

# Probar
pnpm install
pnpm test
pnpm run build

# Si no te gusta, revertir
git merge --abort

Esto te deja hacer smoke testing local del trabajo de un agente sin commitear nada ni afectar al repo principal.

Conflictos y errores comunes

Estos son los siete errores que más veo (y que yo mismo cometí) usando worktrees con agentes.

Error 1: Intentar crear un worktree con una branch ya checkeada en otro

~

# Esto falla:
$ git worktree add ../mi-app.bugfix -b agent/bugfix/login-redirect
fatal: 'agent/bugfix/login-redirect' is already checked out at '/home/user/projects/mi-app'

Causa: Git no permite que dos worktrees tengan checkeada la misma branch al mismo tiempo. Es una invariante del modelo.

Solución: o cambiás de branch en el worktree que la tiene (git checkout main en el repo principal), o creás el nuevo worktree desde otra branch base.

Error 2: Intentar borrar el worktree principal

~

# Esto falla:
$ git worktree remove ~/projects/mi-app
fatal: '/home/user/projects/mi-app' is the main working tree

Causa: el primer worktree de un repo es siempre el "principal" y no se puede borrar vía worktree remove. Se borra borrando el directorio directamente, pero eso te deja sin acceso al .git a través de ese path.

Solución: no borrar el principal. Si querés "empezar de cero", cloná el repo de nuevo.

Error 3: git worktree remove con cambios sin commit

~

# Esto falla (y está bien que falle):
$ git worktree remove ../mi-app.agent-bugfix
fatal: '../mi-app.agent-bugfix' contains modified or untracked files

# Si forzás, perdés todo:
$ git worktree remove --force ../mi-app.agent-bugfix
# ❌ cambios descartados sin aviso

Solución: antes de remover, commiteá, stasheá, o copiá manualmente lo que querés conservar. Usar --force debería ser la excepción.

~

# Si querés conservar los cambios antes de remover:
cd ../mi-app.agent-bugfix
git stash push -u -m "WIP antes de cerrar worktree"
cd ~/projects/mi-app
git stash list   # el stash aparece acá, no se pierde
git worktree remove ../mi-app.agent-bugfix

Error 4: Cambios sin commit "mágicamente" en otro worktree

Un error conceptual común: asumir que commiteás en el worktree A y los cambios aparecen en el worktree B. No es así. Cada worktree tiene su propio working directory e index.

~

# Acá commiteás en worktree A
cd ~/projects/mi-app.agent-refactor
echo "nuevo" >> README.md
git add README.md
git commit -m "docs: agregar nota"

# Y acá NO ves el cambio en el working directory del worktree B
cd ~/projects/mi-app
cat README.md
# Todavía no tiene "nuevo"

# Lo que sí ves: la branch nueva
git branch
# * main
#   agent/refactor/extract-pdf-parser  <-- la branch existe

Causa: los worktrees comparten las refs (agent/refactor/extract-pdf-parser existe en ambos), pero cada uno tiene su propio working tree donde esa branch está checkeada. Para que el working tree de B tenga los cambios, tenés que hacer git checkout agent/refactor/extract-pdf-parser en B.

Error 5: Conflicto porque dos agentes modifican el mismo lockfile

Los lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, Cargo.lock, go.sum) cambian con cualquier commit que sume o actualice una dependencia. Si dos agentes tocan package.json cada uno, el lockfile va a colisionar siempre.

~

# Conflicto típico al mergear dos PRs en paralelo
$ git merge origin/agent/feature/add-csv-export
Auto-merging package.json
CONFLICT (content): Merge conflict in package.json
Auto-merging pnpm-lock.yaml
CONFLICT (content): Merge conflict in pnpm-lock.yaml

Solución: cuando aparece un conflicto de lockfile, lo más rápido es regenerar el lockfile desde cero en lugar de resolver el diff:

~

# Resolver package.json manualmente (son pocos cambios visibles)
# ...

# Regenerar el lockfile desde el package.json mergeado
rm pnpm-lock.yaml
pnpm install     # regenera pnpm-lock.yaml con todas las deps consistentes

git add package.json pnpm-lock.yaml
git commit

Error 6: Path del worktree dentro del repo principal sin ignorar

Ya lo mencioné en setup pero lo repito porque es el error más caro:

~

# Si .worktrees/ no está en .gitignore y commiteás
$ git add .worktrees/
$ git commit -m "feat: setup worktrees"
# Ahora tu repo tiene una copia completa de sí mismo adentro 💀

Prevención: antes de crear el primer worktree, corré git check-ignore -v .worktrees/. Si no devuelve nada, agregalo a .gitignore y commiteá.

Error 7: "Otro proceso está tocando mi repo"

Si tenés un dev server (Next.js, Vite, Rails) corriendo en un worktree y tratás de hacer git worktree remove en otro, no hay conflicto — pero sí lo hay si el servidor tiene un file watcher que está lockeando archivos que Git quiere mover.

Síntoma: git worktree remove se cuelga o devuelve errores de "device or resource busy" en Linux.

Solución: matá el dev server primero.

~

# Encontrar procesos de Node que estén corriendo en ese worktree
lsof +D ~/projects/mi-app.agent-feature | grep node

# O de forma más agresiva
fuser -k ~/projects/mi-app.agent-feature

# Después remové el worktree
git worktree remove ~/projects/mi-app.agent-feature

Limpieza y mantenimiento a largo plazo

Con el uso, los worktrees se acumulan. Una vez por semana (o cuando notes que git worktree list tiene 10 entradas), conviene hacer una pasada de limpieza.

~

# 1. Ver todos los worktrees y sus branches
git worktree list

# 2. Para cada uno, decidir:
#    - ¿El PR ya está mergeado? → remover worktree + borrar branch
#    - ¿El agente sigue trabajando? → dejarlo
#    - ¿El directorio no existe? → dejar la referencia, va a ser podada

# 3. Podar referencias obsoletas
git worktree prune

# 4. Borrar branches locales que ya no existen en remoto
git fetch origin --prune
git branch -vv | grep 'gone]' | awk '{print $1}' | xargs git branch -d

Alias útiles para el día a día

Si usás Bash o Zsh, estos aliases te ahorran tipear:

~

# ~/.bashrc o ~/.zshrc

# Listar worktrees con formato legible
alias wtl='git worktree list'

# Crear worktree rápido para un agente
wtnew() {
  local name=$1
  if [ -z "$name" ]; then
      echo "Uso: wtnew <rol>/<descripcion>"
      return 1
  fi
  local path="../$(basename $(pwd)).agent-${name////-}"
  git worktree add "$path" -b "agent/$name"
  echo "Creado en: $path"
}

# Limpiar worktree y branch merged
wtclean() {
  local path=$1
  local branch=$(git -C "$path" symbolic-ref --short HEAD 2>/dev/null)
  cd "$(git worktree list | awk '/main working tree/ {print $1}')"
  git worktree remove "$path" || echo "Tiene cambios sin commit. Resolvé primero."
  if [ -n "$branch" ]; then
      git branch -d "$branch" 2>/dev/null || echo "Branch $branch no mergeada todavía."
  fi
}

Después de agregarlos a tu shell config, wtnew bugfix/typo-readme te deja listo el worktree en un solo comando.

Cuándo NO usar worktrees

Después de todo lo anterior, también vale la pena ser explícito sobre los casos donde worktrees es la herramienta equivocada:

• Cambios ortográficos o de una sola línea. Si el agente tarda menos de 5 minutos y toca un solo archivo, abrir un worktree es overhead. Hacelo en el repo principal.
• Releases y ambientes totalmente aislados. Si querés un ambiente con otra versión de Node, otra DB, otro OS — un worktree no te da eso. Necesitás un clone, un container, o una VM.
• Reposs enormes con mucho build artifact. Si tu node_modules pesa 3 GB y tenés 5 worktrees, son 15 GB de disco solo para deps. Para repos así, mejor clones separados con cache compartida.
• Cuando el agente no necesita escribir código. Para un agente que solo lee (analizar código, generar documentación a partir de código existente, responder preguntas), no necesitás worktree — alcanza con el repo principal.

Cierre

Git worktrees es la herramienta correcta para coordinar múltiples agentes de programación sobre el mismo repo, y es 100% nativa de Git — no necesitás scripts, ni Docker, ni plugins externos. Tres meses usándola con agentes en producción me dejaron estas conclusiones:

1. Worktrees resuelven el problema de pisarse entre agentes en paralelo mejor que cualquier otra alternativa (clones separados, branches con stash, docker compose).
2. La convención de nombres es lo que hace que escale. Sin agent/<rol>/<descripcion>, en dos semanas no sabés qué branch es de quién.
3. El setup base (.gitignore, alias, naming) toma 15 minutos y te ahorra horas de fricción después.
4. Los errores son todos previsibles. Los siete que listé arriba cubren el 95% de lo que puede salir mal. Si los conocés, los evitás.

Si trabajás con agentes de programación en serio — más de uno en paralelo, más de un día a la vez — worktrees no es opcional. Es la única forma de que los agentes no se rompan entre sí.

Si querés profundizar en cómo orquesto múltiples agentes en pipelines más grandes (con PR review, QA automatizado, y merge a producción), lo cubro en detalle en mi metodología de desarrollo guiado por IA.

¡Gracias por leer! Podés encontrar más sobre mi trabajo y proyectos en mi GitHub.