Codex Worktrees: cómo ejecutar agentes en paralelo con Git
Aprende
cómo funcionan los worktrees de Codex,
cuándo utilizar Local
o Worktree,
qué significa
detached HEAD,
cómo transferir
una tarea
entre Worktree y Local,
crear una rama,
copiar archivos ignorados
con
.worktreeinclude,
configurar setup scripts,
administrar worktrees permanentes
y ejecutar
varios agentes
sin mezclar
sus cambios.
¿Qué son los worktrees de Codex?
Los
worktrees de Codex son checkouts adicionales
de un mismo repositorio Git
que permiten
que distintos agentes
trabajen simultáneamente
sin modificar
el mismo directorio.
Codex puede crear
automáticamente
un worktree
para cada chat,
trabajar inicialmente
en
detached HEAD
y después
permitirte
crear una rama,
abrir ese entorno
en tu IDE
o transferir
el trabajo
al checkout Local.
Por qué usar worktrees con agentes de programación
Paralelismo
Ejecuta varias tareas sobre el mismo repositorio.
Aislamiento
Cada tarea modifica su propio checkout.
Git real
Los worktrees utilizan la funcionalidad nativa de Git.
Background
Deja un agente trabajando mientras tú continúas en Local.
Revisión aislada
Revisa cada diff por separado.
Branch y PR
Convierte el resultado en una rama y Pull Request.
Un repositorio, varios checkouts independientes
Tu checkout
Donde normalmente desarrollas.
Feature
Agente trabajando en login.
Tests
Otro agente aumentando cobertura.
Refactor
Tercer agente trabajando independientemente.
Los worktrees requieren un repositorio Git
Los worktrees solo funcionan cuando el proyecto pertenece a un repositorio Git. Codex utiliza Git worktree como base para crear los checkouts adicionales.
Comprueba:
git statusY también:
git rev-parse --show-toplevelQué es un Git worktree
Normalmente, un repositorio Git tiene un único directorio de trabajo. Los worktrees permiten crear checkouts adicionales vinculados al mismo repositorio.
Repositorio Git
├── Local
│ └── main
│
├── Worktree A
│ └── feature-login
│
├── Worktree B
│ └── tests
│
└── Worktree C
└── refactorPero cada worktree mantiene sus propios archivos de trabajo, índice y estado de checkout.
Dos formas de trabajar con Codex
Foreground
Codex modifica el checkout donde tú también estás trabajando.
- servidor ya configurado
- IDE habitual
- iteración inmediata
- menos aislamiento
Background
Codex trabaja en otro checkout sin modificar directamente tu entorno Local.
- trabajo paralelo
- aislamiento
- varios agentes
- diff independiente
Casos donde un worktree tiene sentido
Ejecutar una feature mientras tú continúas trabajando en otra.
Enviar varias tareas a distintos agentes.
Probar una refactorización sin ensuciar tu checkout.
Investigar una solución alternativa.
Mantener varias ramas abiertas simultáneamente.
Ejecutar agentes de revisión o testing en paralelo.
Cómo crear un worktree administrado por Codex
Abre un chat nuevo
Dentro de Codex en escritorio.
Selecciona Worktree
Cambia el entorno desde Local.
Elige rama base
main, master, feature o tu rama actual.
Envía el prompt
Codex crea el checkout automáticamente.
Así Codex puede ejecutar automáticamente el setup necesario para preparar el nuevo worktree.
Puedes comenzar desde distintas ramas
Feature nueva desde el estado estable.
Continuar trabajo de una feature.
Investigar un bug en una rama.
Partir desde cambios locales existentes.
Si seleccionas una rama que contiene cambios locales sin commit, Codex puede aplicar esos cambios al worktree creado para el chat.
Por qué Codex comienza en detached HEAD
De forma predeterminada,
un worktree
administrado por Codex
no comienza
conectado
a una rama nueva.
Utiliza
el commit
HEAD
de la rama seleccionada
como punto
de partida
y trabaja
inicialmente
en estado
detached HEAD.
git status
# Ejemplo conceptual:
HEAD detached at 8f39a1cCodex puede crear muchos worktrees temporales sin llenar tu repositorio de ramas que quizá nunca necesites.
Dónde guarda Codex los worktrees administrados
$CODEX_HOME/worktrees
Si utilizas
la configuración
predeterminada
de Codex,
CODEX_HOME
suele corresponder
al directorio
de configuración
de Codex.
Desde Settings → Worktrees puedes configurar otra raíz para los worktrees administrados.
Continuar trabajando directamente en el Worktree
Cuando Codex termina una primera implementación, puedes continuar trabajando dentro del mismo worktree.
Abrir el worktree en tu editor.
Usar terminal integrada.
Ejecutar tests y build.
Crear una rama si quieres conservarlo.
Convierte un worktree temporal en trabajo versionado
Si decides conservar el trabajo directamente en ese worktree, puedes utilizar Crear rama aquí para conectar el checkout con una rama Git.
Agente termina
Revisa el resultado.
Ejecuta tests
Comprueba que funciona.
Crear rama aquí
Asigna un nombre.
Commit y push
Guarda el resultado.
Pull Request
Envía para integración.
Transferir el chat de Worktree a Local
Si prefieres continuar el trabajo dentro de tu checkout habitual, usa Transferir / Hand off. Codex gestiona las operaciones Git necesarias para mover el trabajo de forma segura.
Worktree
│
│ Hand off
▼
Local
│
│ Hand off
▼
WorktreeTambién puedes empezar una tarea en Local y transferirla posteriormente a un worktree para que Codex siga trabajando en segundo plano.
Cada chat mantiene asociado su mismo worktree
Si transfieres una conversación desde Worktree hacia Local y después la devuelves, Codex puede regresar al mismo worktree asociado originalmente.
Esto permite pasar un trabajo entre foreground y background sin crear necesariamente un nuevo entorno cada vez.
La misma rama no puede estar activa en dos worktrees
Git evita que una misma rama esté checkout simultáneamente en dos árboles de trabajo.
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'Si quieres probar esa rama dentro de tu checkout Local, lo más simple suele ser utilizar Hand off.
Git protege cada referencia de rama
Una rama Git es una referencia mutable. Operaciones como:
commit
reset
rebase
merge
pueden mover esa referencia. Permitir dos checkouts modificando simultáneamente la misma rama podría generar ambigüedad y condiciones de carrera.
.worktreeinclude: copiar configuración local al nuevo worktree
Los worktrees
comienzan
desde un checkout Git.
Por tanto,
los archivos
ignorados
mediante
.gitignore
no aparecen
automáticamente.
Puedes crear:
# .worktreeinclude
.env.local
config/local.jsonCodex no copia automáticamente todos los archivos no rastreados del checkout Local.
Reglas importantes de .worktreeinclude
Se coloca en la raíz del repositorio.
Acepta rutas
y patrones
similares
a
.gitignore.
Está pensado para archivos ignorados, no para archivos trackeados.
No sobrescribe archivos que ya existen en el checkout.
Codex omite symlinks de origen.
Se aplica a worktrees locales administrados por la app.
AGENTS.override.md ignorado por Git tiene tratamiento especial
Codex puede
copiar automáticamente
un
AGENTS.override.md
ignorado
hacia
sus worktrees
locales administrados.
Ten cuidado al copiar .env y otros secretos
Aunque un archivo local sea necesario para ejecutar el proyecto, cada worktree crea otra copia física de ese archivo.
Prefiere credenciales de desarrollo.
Usa el mínimo conjunto necesario.
Evita credenciales de producción.
Mantén secretos fuera del repositorio.
Prepara cada worktree con Local Environments
Un worktree nuevo puede contener el código, pero no necesariamente todas las dependencias o artefactos necesarios para ejecutar el proyecto.
Para un proyecto Node.js, por ejemplo:
npm install
npm run buildPuedes definir además scripts específicos para macOS, Windows o Linux.
El entorno local se almacena dentro de .codex
mi-proyecto/
├── .codex/
├── AGENTS.md
├── package.json
├── src/
└── tests/Esta configuración puede versionarse en Git para compartir el mismo setup con otros desarrolladores.
Añade acciones rápidas para probar cada worktree
Los Local Environments también permiten definir acciones habituales.
Run
npm startTest
npm testBuild
npm run buildCodex también admite worktrees de larga duración
Un chat
Ligero, temporal y asociado normalmente a una tarea.
Entorno persistente
Se convierte en un proyecto independiente donde puedes iniciar varios chats.
Son adecuados para entornos de desarrollo que quieres conservar durante varias sesiones.
Cuándo crear un worktree permanente
Rama release mantenida varios días.
Feature grande con múltiples chats.
Mantenimiento de otra versión.
Experimento de larga duración.
Codex administra automáticamente los worktrees temporales
De forma predeterminada, Codex mantiene los 15 worktrees administrados más recientes.
El límite puede modificarse o puede desactivarse la eliminación automática desde Configuración.
No solo contiene
archivos
del repositorio:
también puede contener
node_modules,
dependencias,
cachés,
builds
y otros
artefactos.
Cuándo Codex evita eliminar un worktree
Chat asociado fijado.
Chat todavía en curso.
Worktree permanente.
Cuándo puede eliminarse automáticamente
Archivas el chat asociado.
Codex necesita liberar worktrees antiguos para respetar el límite.
Si posteriormente reabres el chat, puede ofrecerte restaurar el trabajo asociado.
Comandos útiles para entender los worktrees
Pero ayudan a comprender qué está haciendo Git por debajo.
Listar worktrees
git worktree listCrear manualmente
git worktree add ../mi-feature feature/mi-featureEliminar
git worktree remove ../mi-featureLimpiar referencias
git worktree pruneNo debes asumir que Git copiará esos archivos cuando crees un worktree manualmente desde terminal.
Ejemplo con cuatro agentes en paralelo
LOCAL
Tú:
desarrollando dashboard
WORKTREE A
Codex:
corregir autenticación
WORKTREE B
Codex:
crear tests de integración
WORKTREE C
Codex:
auditar seguridad
WORKTREE D
Codex:
actualizar documentaciónLa separación funciona mejor cuando las tareas tienen límites razonablemente independientes.
Ejemplo de tareas para distintos worktrees
Worktree A · Bug
Investiga por qué
los usuarios pierden
la sesión después
de actualizar el perfil.
Reproduce el bug,
encuentra la causa raíz,
crea un test de regresión
e implementa
la corrección mínima.Worktree B · Tests
Analiza el módulo
de autenticación.
No cambies comportamiento.
Añade tests
para los flujos
críticos que actualmente
no tengan cobertura.Worktree C · Seguridad
Audita autenticación
y autorización.
Busca únicamente:
- bypass de permisos
- escalada de privilegios
- exposición de sesiones
- CSRF
- validación insuficiente
- filtración de credenciales
No hagas refactors
de estilo.Workflow multiagente para un plugin WordPress
PLUGIN WORDPRESS
LOCAL
Desarrollo principal
WORKTREE A
Corregir AJAX
WORKTREE B
Auditar:
- nonces
- capabilities
- sanitización
- escaping
- SQL
WORKTREE C
Añadir tests PHPUnit
WORKTREE D
Revisar compatibilidad:
- PHP 8.2+
- WordPress
- WooCommerceRevisa cada diff, ejecuta las pruebas y decide qué cambios integrar.
Los worktrees aíslan archivos, pero no eliminan conflictos Git
Dos agentes pueden modificar independientemente la misma función en worktrees distintos. No interferirán mientras trabajan, pero sus ramas podrían entrar en conflicto al integrarse.
Login vs documentación.
API vs frontend aislado.
Dos refactors sobre la misma clase.
Dos migraciones sobre la misma tabla.
Paraleliza por resultados, no por archivos arbitrarios
Por ejemplo:
Corregir login.
Añadir tests del checkout.
Auditar seguridad del REST API.
Migrar módulo de emails.
Qué revisar antes de integrar un worktree
Objetivo
¿Cumplió exactamente la tarea?
Diff
¿Hay cambios no relacionados?
Tests
¿Pasaron las verificaciones?
Seguridad
¿Introdujo nuevos riesgos?
Compatibilidad
¿Mantiene contratos existentes?
Integración
Branch, commit y PR.
Haz que cada agente deje su worktree listo para revisión
Antes de terminar:
1. ejecuta los tests relevantes
2. ejecuta lint/typecheck/build si existen
3. revisa todo el diff
4. elimina debugging temporal
5. comprueba cambios accidentales
6. confirma que no modificaste archivos fuera del alcance
Después entrégame:
- resumen
- archivos modificados
- tests ejecutados
- resultados
- riesgos pendientes
- recomendaciones para integrar este worktree.Problemas habituales con Codex Worktrees
| Problema | Qué revisar |
|---|---|
| Proyecto sin Git | Inicializa o abre el repositorio correcto |
| Falta .env | .worktreeinclude |
| Faltan dependencias | Setup script del entorno local |
| Rama ya utilizada | Otro worktree tiene esa rama checkout |
| El servidor no inicia | Puerto o configuración compartida |
| Mucho uso de disco | Worktrees, dependencias y cachés antiguos |
| Conflictos al integrar | Tareas paralelas tocaron el mismo código |
| Chat archivado y worktree desaparecido | Restaurar snapshot si está disponible |
Cómo trabajar mejor con varios worktrees
Un objetivo independiente por chat.
Empieza desde una rama conocida.
Automatiza instalación y build.
Añade solo archivos ignorados necesarios.
Evita credenciales de producción.
Revisa el diff antes de crear la rama.
No paralelices tareas altamente dependientes.
Limpia entornos que ya no necesitas.
Local, Worktree o Cloud: cuál elegir
Cómo usar Codex Worktrees de principio a fin
Define la tarea
Un resultado concreto.
Selecciona Worktree
Aísla el trabajo.
Elige rama base
Parte de un estado conocido.
Ejecuta setup
Dependencias y build.
Codex implementa
Trabajo aislado.
Verifica
Tests, lint y build.
Revisa diff
Comprueba alcance y calidad.
Decide destino
Branch o Hand off a Local.
Integra
Commit, push y PR.
Guías relacionadas
Documentación oficial recomendada
Git Worktrees
Creación, detached HEAD, Hand off, worktrees permanentes, .worktreeinclude y limpieza.
Local Environments
Setup scripts, Actions y configuración compartida en .codex.
Codex Desktop
Proyectos, repositorios, terminales y herramientas de desarrollo.
FAQ sobre Codex Worktrees
Es un checkout adicional de un repositorio Git que Codex puede utilizar para trabajar en una tarea sin modificar directamente tu checkout Local.
Sí. Los worktrees utilizan Git worktree internamente, por lo que el proyecto debe pertenecer a un repositorio Git.
Un worktree administrado comienza normalmente en el commit HEAD de la rama seleccionada, pero sin crear automáticamente una rama nueva. Esto permite mantener worktrees temporales sin llenar el repositorio de ramas innecesarias.
Los worktrees administrados se crean por defecto bajo $CODEX_HOME/worktrees. Puedes cambiar la ubicación desde Settings → Worktrees.
Sí. La función Hand off permite mover un chat entre Worktree y Local. Codex gestiona las operaciones Git necesarias para mover el trabajo entre ambos checkouts.
Sí. Hand off funciona en ambas direcciones. Puedes mover un chat desde Local hacia un worktree para que Codex continúe trabajando en segundo plano.
Es un archivo situado en la raíz del repositorio que indica qué archivos ignorados por Git debe copiar Codex a los nuevos worktrees locales administrados.
No necesariamente. Los archivos ignorados por Git deben coincidir con las reglas de .worktreeinclude para que Codex los copie a un worktree local administrado.
Sí. Puedes utilizar Crear rama aquí para convertir el trabajo en una rama, hacer commit, push y crear posteriormente un Pull Request.
No. Git impide que una misma rama esté checkout simultáneamente en más de un worktree. Para mover el trabajo a Local, utiliza Hand off.
Por defecto, Codex conserva los 15 worktrees administrados más recientes. Puedes cambiar ese límite o desactivar la eliminación automática desde Configuración.
Antes de eliminar un worktree administrado, Codex guarda una instantánea del trabajo. Si vuelves a abrir el chat asociado, puede ofrecerte restaurar el worktree.
Los worktrees administrados están pensados principalmente para una tarea o chat y pueden limpiarse automáticamente. Un worktree permanente se conserva como proyecto de larga duración y puede albergar varios chats.
Codex Skills: crea workflows reutilizables para tus agentes
Ya sabes cómo ejecutar varias tareas en entornos aislados. Ahora veremos cómo crear Skills reutilizables para que Codex conozca procedimientos, checklists, scripts y recursos especializados sin repetir las mismas instrucciones en cada prompt.
Aprender Codex Skills →