Guía práctica de Codex Worktree: desarrolla varias tareas de IA en paralelo sin ensuciar tu repositorio

En un mismo repositorio están corriendo tres tareas a la vez: fix/auth-expired-session, test/payment-webhook y docs/setup-node20. El git status del main checkout se vuelve una mezcla de cambios sin relación: la corrección del bug de login, archivos fixture de tests y una nota en el README sobre Node 20. Los tres tipos de cambio viven en un solo checkout, y ya no queda claro qué parte se puede commitear sola ni cuál puede afectar a las demás.

Esto no es un problema abstracto de “tareas paralelas”. Es la consecuencia real de contaminar un checkout de Git. El modo Worktree de Codex app separa distintas tareas en directorios y ramas diferentes, para que cada línea de trabajo tenga un diff revisable, mergeable y reversible.

Local / Worktree / Cloud: cómo elegir el modo correcto

Codex app admite tres modos de ejecución. Local y Worktree se ejecutan en tu computadora. La documentación oficial lo dice de forma directa: “Both Local and Worktree threads will run on your computer”. Cloud, en cambio, se ejecuta en un entorno remoto.

Worktree encaja con tareas paralelas independientes o con pruebas de ideas nuevas. Cada thread tiene su propio directorio y rama, así que el main checkout no se ve afectado. Local es simple, pero cuando varias tareas se mezclan, separar commits se vuelve difícil. Cloud se aleja por completo de tu equipo local y encaja con CI/CD y builds remotos.

La regla de elección: usa Local para una sola tarea, Worktree para trabajo local paralelo o experimental, y Cloud para trabajo remoto.

El modo Worktree de Codex app en detalle

Creación de Worktree y Handoff

El flujo para crear un Worktree thread en Codex app es:

1. Crear un nuevo thread
2. Elegir el modo Worktree (el nombre exacto en la UI puede cambiar después del 18/06/2026)
3. Elegir una rama de inicio, o trabajar por defecto en detached HEAD
4. Enviar el primer prompt
5. Codex empieza a trabajar en un directorio aislado

Por defecto, Codex trabaja en detached HEAD. Eso permite seguir operando dentro del worktree y crear una rama cuando quieras conservar el resultado. Handoff sirve para mover el thread y el código entre Local y Worktree.

Escenarios de Handoff:

De Worktree a Local: cuando la tarea termine, primero crea una rama dentro del worktree si todavía estás en detached HEAD. Luego usa Handoff para volver a Local y finalmente haz merge o crea una PR.

De Local a Worktree: cuando quieras mover trabajo inacabado a un entorno aislado para evitar ensuciar el main checkout.

Handoff no es solo cambiar de directorio. También mueve el contexto del thread, el historial de prompts y los cambios inacabados.

Particularidades de los Codex-managed worktrees

Los Codex-managed worktrees tienen varios comportamientos especiales:

Ubicación por defecto: $CODEX_HOME/worktrees

Cantidad conservada por defecto: 15 worktrees (según la documentación del 18/06/2026); los más antiguos pueden limpiarse automáticamente

Permanent worktree: un worktree creado manualmente no se borra automáticamente

Límite de rama: Git no permite que la misma rama esté checked out en varios worktrees al mismo tiempo; intentarlo produce un error

Herencia de reglas: AGENTS.override.md se copia automáticamente al worktree para mantener coherentes las reglas del proyecto

En la práctica: la cantidad de worktrees tiene límite, los antiguos pueden limpiarse, la misma rama no puede usarse en paralelo y las reglas del proyecto se heredan.

.worktreeinclude resuelve el problema de archivos ignorados

Por defecto, un worktree hereda solo Git tracked files. Los archivos en .gitignore no se mueven automáticamente durante Handoff. Los faltantes habituales son .env, .env.local, cachés de dependencias y archivos de configuración local.

La solución es crear un archivo .worktreeinclude en la raíz del proyecto y listar los archivos ignorados que se deben copiar. Ejemplo:

.env
.env.local
node_modules/.cache

Con eso, los archivos ignorados listados ahí también pueden copiarse al worktree durante Handoff.

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

Setup scripts: hacer que el proyecto arranque dentro de un worktree

Un worktree está en otro directorio, así que puede faltarle dependencias o archivos que nunca se hicieron check in. Los setup scripts se ejecutan cuando se crea un nuevo worktree o empieza un nuevo thread, para dejar el entorno usable.

Pasos de configuración:

1. Configurar setup steps en Local environments dentro de Codex app
2. Crear un directorio .codex para archivos de configuración
3. Escribir scripts específicos por plataforma

Ejemplo para un proyecto Node.js:

# .codex/setup.sh
npm install
npm run build

Ejemplo para un proyecto Python:

# .codex/setup.sh
pip install -r requirements.txt
python manage.py migrate

Los setup scripts se ejecutan para cada worktree nuevo y reducen la instalación manual de dependencias. La UI de configuración y el formato de archivos pueden cambiar después del 18/06/2026, así que revisa la documentación actual antes de depender de nombres exactos.

Sin Codex app, Plain Git worktree también aísla el trabajo

Si prefieres CLI o terminal, puedes crear directorios aislados directamente con Git worktree y luego iniciar Codex dentro de cada directorio. No necesitas la gestión de Codex app, pero tendrás que administrarlo todo manualmente.

Comandos frecuentes de Git worktree:

# Crear un nuevo worktree y una rama, siguiendo el estilo del caso de uso oficial
git worktree add ../analysis-highway-eda -b analysis/highway-eda

# Crear un nuevo worktree desde una rama existente
git worktree add ../task-b existing-branch

# Listar todos los worktrees
git worktree list

# Eliminar un worktree
git worktree remove ../task-a

# Limpiar metadatos obsoletos de worktree
git worktree prune

Comparación entre Codex-managed y Plain Git:

Plain Git worktree encaja con desarrolladores que prefieren CLI, pero tendrás que gestionar instalación de dependencias, entorno y limpieza. Los Codex-managed worktrees automatizan más de ese trabajo.

¿Las automations en segundo plano deberían usar worktree?

En un repositorio Git, una automation puede ejecutarse en el local project o en un dedicated background worktree. La elección depende del tipo de tarea y del control de riesgo.

Lógica de decisión:

Local sirve para tareas puntuales y pruebas temporales. Modifica directamente el main checkout, por lo que puede contaminar trabajo inacabado. Si estás editando un archivo, una background automation podría modificar el mismo archivo.

Worktree sirve para tareas repetidas o programadas. Aísla automation changes de unfinished local work. La automation se ejecuta en un directorio independiente y no afecta al main checkout.

Notas de riesgo:

Automations usa default sandbox settings, que pueden cambiar después del 18/06/2026

Con full access, las background automations son más riesgosas, así que conviene usar worktree

No ejecutes tareas repetidas en segundo plano directamente en Local

Principio: una tarea temporal puntual puede usar Local; tareas repetidas y trabajo en segundo plano con full access deberían usar Worktree.

Qué tareas se pueden paralelizar y cuáles deben ser secuenciales

Los casos de uso oficiales recomiendan separar exploraciones distintas en worktrees diferentes. En la práctica, igual hay que juzgar conflictos de archivos y dependencias entre tareas.

Tabla de decisión para tareas paralelas:

Reglas de paralelización:

Empieza con dos tareas pequeñas e independientes, no con cinco o seis.

Mantén el número de tareas en 3-4 para reducir el costo de revisión.

Da a cada tarea un criterio claro de verificación.

No sobreparalelices. Cuantas más tareas paralelas, mayor el costo de revisión y el riesgo de merge conflict.

Plantilla de tarjeta de tarea: deja claro qué hará cada worktree

Antes de iniciar un worktree, conviene describir bien la tarea para facilitar revisión y seguimiento.

Ejemplo de tarjeta de tarea:

Goal: "Corregir el bug session expired del módulo auth"
Context:
  - "La sesión expira después de 30 minutos, pero el frontend no muestra aviso"
  - "Archivos relacionados: src/auth/session.js, src/components/AuthProvider.jsx"
Constraints:
  - "No cambiar el schema de la base de datos"
  - "No introducir nuevas dependencias"
Done when:
  - "El frontend muestra un aviso cuando la sesión expira"
  - "npm test pasa"
  - "El flujo de login se prueba manualmente"

Branch/Worktree: "fix/auth-expired-session"
Comando de verificación: "npm test && npm run lint"

Puntos a completar:

Goal: describe el objetivo en una frase

Context: da contexto de archivos, módulo y antecedentes

Alibaba Cloud - Opción preferida para desarrolladores, 15 % de descuento exclusivo en Lighthouse

Obtener 15% dto. →Anuncio

Constraints: define límites, incluido qué no cambiar

Done when: lista criterios verificables de finalización

Branch/Worktree: usa un nombre claro como task-type/module-description

Comando de verificación: da un comando concreto y ejecutable

Así cada worktree tiene límites claros. En la revisión, compara el resultado con Done when.

Cola de merge: revisar, probar y mezclar de uno en uno

Cuando las tareas paralelas terminan, no vuelques todos los resultados en main a la vez. Ordénalos por riesgo, y luego revisa, prueba y mezcla uno por uno.

Pasos de la cola de merge:

1. Ordenar worktrees por riesgo, empezando por el menor
2. Para el primer worktree:
   • Ejecutar el comando de verificación: tests, lint
   • Revisar el diff y confirmar el alcance de cambios
   • Crear una rama si todavía está en detached HEAD
   • Revisar el diff según tus reglas de PR review
3. Hacer merge a Local o crear una PR:
   • Merge local: Handoff de vuelta a Local y luego merge
   • Merge por PR: crear una PR y esperar CI y review
4. Repetir el proceso con el siguiente worktree
5. Cuando todo termine, hacer merge a la rama main

Checklist de verificación:

Los comandos de verificación pasan: tests y lint

Revisión del diff: el alcance de cambios coincide con la tarea

Review guidelines: sin archivos sensibles ni secrets hard-coded

CI pasa, si existe

Flujo de prueba manual completo

Notas de riesgo:

No prometas que los resultados de varios worktrees se mezclarán automáticamente

Si varias tareas editan el mismo archivo, resuelve conflictos manualmente

Mantén revisión humana y tests en el proceso

La idea de una cola de merge es que el diff de cada línea de trabajo sea revisable y reversible, no enviar todos los cambios de una sola vez.

Checklist de troubleshooting

Error "branch already used by worktree"

Causa: la rama ya está ocupada por otro worktree

Solución:

Usa git worktree list para ver qué ramas están ocupadas

Elige otra rama o elimina el worktree que está usando esa rama

El código no corre dentro del worktree

Causa: faltan dependencias o archivos de configuración

Pasos de diagnóstico:

Revisa si existen .env y .env.local; puede que no se hayan copiado

Revisa si las dependencias están instaladas, como node_modules o venv

Revisa si los archivos de configuración están completos

Solución:

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Configura .worktreeinclude para copiar ignored files

Configura Setup scripts para instalar dependencias automáticamente

El espacio en disco de worktree crece demasiado

Causa: automations frecuentes crean muchos worktrees

Solución:

Archiva automation runs que ya no necesites

Ejecuta manualmente git worktree prune para limpiar worktrees obsoletos

Revisa la configuración de retención de worktrees en Codex app, que puede cambiar después del 18/06/2026

Un worktree creado por el agent no coincide con el UI/thread context

Causa: cuando el agent crea un worktree automáticamente, puede saltarse la App UI

Solución:

Usa git worktree list para inspeccionar todos los worktrees

Revisa manualmente en la app la vinculación entre thread y worktree

Evita pedirle al agent que cree worktrees automáticamente; créalos desde la App UI

El hábito básico de troubleshooting es inspeccionar primero el estado de worktree con git worktree list y luego actuar según el tipo de error.

Costo: las tareas paralelas consumen cuota más rápido

Las tareas paralelas tienden a consumir más turnos o cuota. Cada worktree es una session independiente, y Codex contabiliza cada session por separado.

Reglas de costo:

Mantén las tareas paralelas alrededor de 3-4.

Empieza con dos tareas pequeñas e independientes para reducir el costo de revisión.

Da a cada tarea un criterio claro de verificación para evitar iteraciones infinitas.

Para precios, cuota y detalles de plan, usa un futuro artículo de Cost & Quota. Esta página no repite cifras sin verificar.

Siguientes pasos y lecturas relacionadas

Artículos anteriores:

Elección de entrada en Codex: breve introducción a los modos Local / Worktree / Cloud

Reglas de proyecto AGENTS.md: cómo cada worktree hereda el mismo conjunto de reglas del proyecto