Git worktrees para coding agents: un checkout por agente, no un caos

Un coding agent que corre git checkout -b su-rama en el mismo directorio donde tú editas no es “ágil”: te deja el commit huérfano y a otro worker en una rama ajena. Git ya resolvió esto: varios working trees ligados al mismo objeto store. El comando es git worktree. No es un producto de un vendor; es el manual de Git.

Esta guía no sustituye sandboxing y permisos ni el ranking de mejores agentes de código. Aquí el contrato es uno: cada agente vive en un path, cada path tiene su HEAD.

Qué es un worktree (oficial)

Un repositorio tiene un worktree principal (el de git clone / git init) y cero o más linked worktrees. Comparten objetos, refs y config del repo; no comparten HEAD ni index. Cuando terminas, git worktree remove. Si borras la carpeta a mano, los metadatos en .git/worktrees/ se limpian con git worktree prune (o gc.worktreePruneExpire).

Regla que tumba a los agentes: una rama no puede estar checked out en dos worktrees. Sin -f, git worktree add se niega. Por eso el agente que “toma main” en tu checkout bloquea al resto.

El protocolo de 60 segundos

Desde el repo principal:

git fetch origin
git worktree add -b agent/hotfix-login ../agent-hotfix-login origin/main
cd ../agent-hotfix-login
# aquí corre el agente

add <path> sin -b nombra la rama como el último componente del path (hotfix si el path termina en hotfix). Con -b fijas el nombre. Para experimentar sin rama: git worktree add --detach ../agent-scratch.

Cuando el PR está listo:

git -C ../agent-hotfix-login status   # limpio
git worktree remove ../agent-hotfix-login

Si hay cambios, Git se niega; usa -f solo si tú aceptas perder el working tree (no el objeto commit: el commit sigue en el repo).

Comando	Para qué	Trampa
add -b <rama> <path> <commit>	Sesión nueva del agente	Rama ya checked out → error; no uses -f por default
add --detach <path>	Spike / tests	HEAD suelto; fácil “perder” el commit si no lo etiquetas
list	Ver path, rama, locked, prunable	El principal sale primero
lock --reason 'usb'	Disco no siempre montado	Evita prune automático y move/remove
prune	Basura de carpetas borradas a mano	No borra tu código; borra admin files huérfanos
remove	Cerrar la sesión	Falla con dirty tree; eso es una feature

Por qué los agentes lo rompen

1. Checkout en el principal. El agente cree que “cambiar de rama” es barato. En un linked worktree, cambiar de rama está bien dentro de su path. Robar el principal no.
2. node_modules por árbol. Cada worktree es un directorio real. Hay que pnpm install (o copiar). No es un bug de Git.
3. Hooks y .env. Archivos no trackeados no viajan. Copia o symlink explícito; no asumas que el agente ve tus secretos (y mejor que no).
4. Submódulos. git worktree move no mueve worktrees con submódulos. repair reengancha paths si moviste el principal a mano.

Receta para Claude Code / Codex / CLI

• Worktree hermano, nunca cd al principal del humano.
• Rama agent/<ticket> desde origin/main, no desde un dirty HEAD local.
• El agente hace commit en su rama; push + PR. Nunca checkout main en el principal.
• Al terminar: remove, no rm -rf (deja admin files).
• Varios agentes en paralelo = varios paths. El techo es disco, no Git.

Si el agente necesita “el mismo repo” para leer historia, ya lo tiene: los objetos son compartidos. Lo que no comparte es tu index sucio.

El curso instalar un agente cubre el loop local. El aislamiento de filesystem/sandbox es la otra capa; worktrees aíslan Git, no la red.

Checklist antes de soltar el agente

• git worktree list muestra el principal y el path del agente, ramas distintas.
• El principal no está en la rama del agente (y viceversa).
• origin/main fresco: git fetch antes del add.
• .env no copiado a menos que el ticket lo pida; nunca commitear.
• CI corre en el PR, no “en tu working tree sucio”.
• Al merge: worktree remove, luego borra la rama local si el remoto ya squash-mergeó.

Si dos loops de 15 minutos comparten un checkout, el segundo git checkout -b huérfana el commit del primero. Worktrees no son estilo: son el único arreglo barato que Git documenta.

FAQ

¿Puedo tener dos worktrees en main? No, salvo force. Crea agent/read-main desde el mismo commit: git worktree add ../read origin/main si main no está checked out; o --detach.

¿clone extra es más simple? Sí, y duplica objetos. Worktree es el atajo correcto cuando el repo es grande.

¿Lock sirve para agentes? Sí si el path está en un volumen que se desmonta. Si no, YAGNI.

¿Qué pasa si el agente borra la carpeta? git worktree list marca prunable; prune limpia. El commit, si se hizo, sigue en el repo (git branch -v / git log).

Verificado 2026-09-03 contra git help worktree y https://git-scm.com/docs/git-worktree (manual 2.54+).