Git Worktrees como Primitivo de Orquestación: 5 Agentes en Paralelo en el Mismo Repo sin Conflictos

El problema clásico de ejecutar múltiples agentes de codificación en paralelo no es de cómputo — es de estado de archivos. Cuando lanzas 5 agentes simultáneos en el mismo repositorio con git checkout, todos compiten por el mismo índice de git, los mismos branches y el mismo directorio de trabajo. El resultado es un estado indeterminado que ninguno puede resolver de forma confiable.

La solución existe en git desde hace años y la mayoría de los ingenieros nunca la ha usado en producción: git worktree.

Addy Osmani documentó este patrón en el contexto de agentes de codificación. Este artículo va más allá del tutorial básico y cubre lo que importa en producción: gestión de recursos, limpieza automática y los aliases que hacen el flujo de trabajo más fluido.

Qué es un worktree, técnicamente

Un worktree es un directorio de trabajo separado vinculado al mismo repositorio git. Cada worktree:

• Tiene su propio árbol de trabajo (archivos en disco)
• Está en un branch diferente (obligatorio — dos worktrees no pueden estar en el mismo branch)
• Comparte el mismo .git/objects (commits, historial, refs)
• Es invisible para los otros worktrees durante la ejecución

Esto significa que cada agente tiene aislamiento completo del estado de archivos, pero acceso al mismo historial compartido. Cuando termina, hace push del branch y abre un PR — igual que cualquier desarrollador humano.

# Estructura con 3 worktrees activos
$ git worktree list
/Users/dev/mi-repo           abc1234 [main]
/Users/dev/mi-repo-feat-a    def5678 [auto/feat-a]
/Users/dev/mi-repo-feat-b    ghi9012 [auto/feat-b]
/Users/dev/mi-repo-hotfix    jkl3456 [auto/hotfix-login]

Cada línea es un directorio separado, cada uno ejecutando un agente diferente, sin ninguna interferencia.

Por qué esto importa para la orquestación de agentes

El enfoque convencional para orquestar agentes de codificación utiliza una de estas opciones:

1. Un repositorio por agente — alto overhead, dificulta compartir el código base
2. Branches aislados en el mismo repo, con clone — funciona, pero duplica .git/objects y es lento
3. Agentes secuenciales — elimina el paralelismo que buscas

Los worktrees son la cuarta opción: paralelo, mismo repo, sin duplicación, sin conflicto.

El overhead de crear un worktree es mínimo — es esencialmente crear un directorio con un HEAD apuntando a un nuevo branch. Sin copiar objetos git. Iniciar un nuevo agente en un worktree tarda segundos, no minutos.

Los worktrees convierten git de sistema de control de versiones en sistema de aislamiento de contexto para agentes. No estás ejecutando múltiples checkouts — estás ejecutando múltiples agentes en el mismo repo con seguridad de estado garantizada.

Setup: aliases bash para un flujo de trabajo fluido

Agrega a tu ~/.bashrc o ~/.zshrc:

# Crear worktree para un agente (convención de nombre automática)
wt-agent() {
  local REPO_ROOT
  REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
  if [[ -z "$REPO_ROOT" ]]; then
    echo "No estás dentro de un repositorio git." >&2
    return 1
  fi

  local TASK="${1:?Uso: wt-agent <nombre-tarea>}"
  local BRANCH="auto/${TASK}"
  local WORKTREE="${REPO_ROOT%/*}/$(basename "$REPO_ROOT")-${TASK}"

  git -C "$REPO_ROOT" worktree add "$WORKTREE" -b "$BRANCH"
  echo "Worktree creado: $WORKTREE (branch: $BRANCH)"
  echo "cd $WORKTREE"
}

# Listar worktrees activos con estado resumido
wt-list() {
  git worktree list --porcelain | awk '
    /^worktree /  { wt=$2 }
    /^branch /    { br=$2 }
    /^HEAD /      { hd=substr($2,1,7) }
    /^$/          { printf "%-50s %-30s %s\n", wt, br, hd }
  '
}

# Eliminar worktree y borrar branch local tras merge
wt-clean() {
  local TASK="${1:?Uso: wt-clean <nombre-tarea>}"
  local REPO_ROOT
  REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
  local WORKTREE="${REPO_ROOT%/*}/$(basename "$REPO_ROOT")-${TASK}"
  local BRANCH="auto/${TASK}"

  git worktree remove "$WORKTREE" --force
  git branch -d "$BRANCH" 2>/dev/null || echo "Branch $BRANCH no encontrado localmente"
  echo "Worktree y branch eliminados: $TASK"
}

# Lanzar agente Claude Code en un worktree (requiere claude CLI)
wt-claude() {
  local TASK="${1:?Uso: wt-claude <nombre-tarea> [prompt]}"
  local PROMPT="${2:-}"
  local REPO_ROOT
  REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
  local WORKTREE="${REPO_ROOT%/*}/$(basename "$REPO_ROOT")-${TASK}"

  if [[ ! -d "$WORKTREE" ]]; then
    wt-agent "$TASK"
  fi

  if [[ -n "$PROMPT" ]]; then
    claude --cwd "$WORKTREE" --print "$PROMPT" &
    echo "Agente lanzado en segundo plano (PID: $!)"
  else
    claude --cwd "$WORKTREE"
  fi
}

Con estos aliases, el flujo para lanzar 5 agentes en paralelo queda así:

# Terminal 1 — agente de refactoring
wt-claude "refactor-auth" "Refactoriza el módulo de autenticación para usar el nuevo proveedor JWT"

# Terminal 2 — agente de tests
wt-claude "add-tests-payment" "Escribe tests unitarios para todos los handlers del módulo de pagos"

# Terminal 3 — agente de docs
wt-claude "update-api-docs" "Actualiza la documentación de la API con los nuevos endpoints del #123"

# Terminal 4 — agente de bug fix
wt-claude "fix-session-leak" "Corrige el memory leak en la gestión de sesiones (issue #456)"

# Terminal 5 — agente de migración
wt-claude "migrate-db-schema" "Escribe la migración para añadir índice compuesto en la tabla de eventos"

Cada comando lanza un agente en segundo plano, en un worktree aislado, en un branch separado. Monitoreas vía wt-list.

Patrón de coordinación: el agente orquestador

Para tareas interdependientes, usa un agente orquestador que despacha subtareas a agentes worker mediante worktrees:

#!/usr/bin/env bash
# orchestrate.sh — Ejemplo de orquestrador simple

REPO_ROOT=$(git rev-parse --show-toplevel)
TASKS=("fix-auth-bug" "add-auth-tests" "update-auth-docs")
PIDS=()

# Lanzar agentes en paralelo
for TASK in "${TASKS[@]}"; do
  WORKTREE="${REPO_ROOT%/*}/$(basename "$REPO_ROOT")-${TASK}"
  git worktree add "$WORKTREE" -b "auto/${TASK}" 2>/dev/null

  claude --cwd "$WORKTREE" --print \
    "Tu tarea: ${TASK}. Al terminar, haz commit y push del branch auto/${TASK}." \
    &

  PIDS+=($!)
  echo "Agente ${TASK} lanzado (PID: ${PIDS[-1]})"
done

# Esperar a que todos terminen
for PID in "${PIDS[@]}"; do
  wait "$PID" && echo "Agente $PID completado" || echo "Agente $PID falló"
done

Límites y precauciones

Los worktrees resuelven el problema del estado de archivos, pero no eliminan todos los conflictos de coordinación:

Lo que los worktrees NO resuelven:

• Dos agentes editando el mismo archivo en branches diferentes siguen generando conflicto de merge en el PR.
• Locks de base de datos o recursos externos necesitan coordinación externa.
• El límite de worktrees simultáneos depende del filesystem — en NFS o volúmenes lentos, cada worktree adicional tiene costo real de I/O.

Mejores prácticas:

# Antes de crear worktrees, definir particionamiento explícito de archivos
# Agente A: src/auth/**
# Agente B: src/payment/**
# Agente C: src/notifications/**
# → sin solapamiento → sin conflicto de merge

Artículos relacionados

Fuentes primarias: git-worktree — documentación oficial · Addy Osmani — Code Agent Orchestra