Git worktree con Claude Code y Codex: guía práctica

Si ejecutas más de un agente de programación en un mismo repositorio, necesitas git worktrees. Permiten que cada agente trabaje en su propio branch y en su propia carpeta, a la vez, sin pisar el trabajo de los demás.

¿Qué es un git worktree?

Un clon normal tiene un único árbol de trabajo: una carpeta y un branch activo. Un worktree es una carpeta de trabajo extra vinculada al mismo repositorio, con otro branch activo. Todos los worktrees comparten el mismo historial .git, así que los commits que hagas en cualquiera de ellos se ven al instante en los demás, pero sus archivos están separados.

Para los agentes, eso significa que:

• Claude Code puede editar archivos en ../atlas-auth sobre feat/auth
• Codex puede editar archivos en ../atlas-search sobre feat/search
• Tú sigues revisando y ejecutando la app en la carpeta principal sobre main

Nadie sobrescribe los cambios de nadie.

Crea un worktree por tarea

Desde la carpeta principal de tu repositorio:

# new branch + new folder next to the repo
git worktree add ../atlas-auth -b feat/auth
 
# another one, starting from a specific branch
git worktree add ../atlas-search -b feat/search origin/main
 
# see them all
git worktree list

Después, inicia un agente en cada carpeta:

cd ../atlas-auth && claude
cd ../atlas-search && codex

Ponle a cada carpeta el nombre de su tarea. Dentro de un mes atlas-auth seguirá diciéndote algo; wt2, no.

O deja que Claude Code cree el worktree

Las versiones recientes de Claude Code pueden crear el worktree por ti:

claude --worktree feature-auth   # or: claude -w feature-auth

Esto crea un worktree en .claude/worktrees/feature-auth/ sobre un branch nuevo llamado worktree-feature-auth y arranca Claude dentro. Ejecútalo otra vez con otro nombre en una segunda terminal y tendrás una segunda sesión aislada. También puedes pedirle a Claude que «trabaje en un worktree» en mitad de una sesión.

Algunos detalles de la documentación de worktrees de Claude Code:

• Añade .claude/worktrees/ a tu .gitignore para que los archivos de los worktrees no aparezcan como no rastreados en tu checkout principal.
• El repositorio necesita al menos un commit.
• Al salir, Claude elimina un worktree limpio (si tiene nombre, te pregunta antes) y te pregunta si quieres conservar uno que todavía tenga cambios.
• Un archivo .worktreeinclude indica los archivos ignorados por git, como .env, que se copian en cada worktree nuevo.

Usa claude --worktree cuando Claude Code sea el único agente de la tarea. Usa git worktree add a secas cuando quieras elegir tú la carpeta y el nombre del branch, o ejecutar Codex u otro agente en el worktree.

Prepara cada worktree antes de que empiece el agente

Un worktree nuevo solo contiene los archivos rastreados por git. Antes de pasárselo a un agente:

• Instala las dependencias. node_modules, los entornos virtuales y las carpetas de compilación no se comparten. Ejecuta npm install (o su equivalente) en cada worktree. Los gestores de paquetes con almacén compartido, como pnpm, lo hacen rápido.
• Copia la configuración no rastreada. Los archivos .env y los ajustes locales suelen estar ignorados por git, así que copia lo que la app necesite para arrancar. Con claude --worktree, mejor indícalos en .worktreeinclude.
• Usa puertos distintos. Dos servidores de desarrollo no pueden escuchar los dos en el puerto 3000. Arranca el segundo en otro puerto, por ejemplo PORT=3001 npm run dev.
• Comparte las instrucciones con archivos rastreados. CLAUDE.md y AGENTS.md están en git, así que cada worktree los recibe automáticamente.

Revisar, fusionar y limpiar

Cuando un agente termina:

# in the worktree: check the work
git diff main...feat/auth
npm test
 
# in the main folder: merge
git merge feat/auth
 
# remove the worktree folder and its registration
git worktree remove ../atlas-auth
git branch -d feat/auth

Si borraste a mano la carpeta de un worktree, ejecuta git worktree prune para limpiar la entrada obsoleta.

Errores habituales

• «Branch is already checked out». Un branch solo puede estar activo en un worktree a la vez. Crea un branch nuevo para cada worktree.
• Worktrees olvidados. Los worktrees antiguos mantienen branches vivos y ocupan disco. Ejecuta git worktree list de vez en cuando.
• Cambios sin confirmar al eliminarlo. git worktree remove se niega si el worktree tiene cambios. Haz commit o stash antes, o usa --force si de verdad quieres descartarlos.
• Agentes que editan la carpeta principal. Inicia cada agente desde dentro de la carpeta de su worktree, no desde la raíz del repositorio.

Worktrees en Vibe Console

Vibe Console mantiene los worktrees a la vista mientras los agentes trabajan en ellos:

• La pestaña Worktrees de Control de código fuente (⌘⇧G) muestra cada worktree con su branch, y marca el principal y los checkouts desacoplados (detached).
• Arrastra un worktree a una terminal para pegar su ruta y luego inicia allí un agente con ⌘K.
• Eliminar worktree lo limpia cuando terminas y te pide Forzar eliminación si todavía tiene cambios locales. El worktree principal está protegido.
• La cuadrícula muestra hasta nueve terminales, así que el agente de cada worktree puede tener su propio panel. Consulta cómo ejecutar agentes en paralelo.

Crea los worktrees con git worktree add o claude --worktree como se explica arriba; los dos aparecen en la lista al instante.

Preguntas frecuentes

¿Los worktrees ocupan mucho espacio en disco?

Solo lo que ocupen los archivos del branch y lo que instales en ellos. El historial de git es compartido.

¿Uso worktrees o clones separados?

Worktrees. Comparten un único historial, así que los branches y los commits están disponibles al instante en todas partes, y limpiar es un solo comando.

¿Pueden dos agentes compartir un worktree?

Solo si como mucho uno de ellos edita archivos. Un agente revisor que solo lee puede compartir worktree con el agente que escribe el código.

Pruébalo gratis durante 14 días: descarga Vibe Console.