Codex CLI: cómo usar worktrees de Git

Configuración mínima de Codex CLI

Necesitas Codex CLI 0.154.0, un repositorio Git local y la función experimental worktrees activada. Comprueba la versión antes de buscar una opción que un binario anterior todavía no reconoce.

codex --version
npm install -g @openai/codex@0.154.0
codex features enable worktrees
codex features list

El comando persistente guarda esta preferencia en la configuración de Codex. Si solo quieres probarla una vez, no cambies la configuración y añade --enable worktrees a esa ejecución.

Ahora puedes iniciar una sesión aislada, lanzar una tarea sin interfaz o bifurcar una conversación existente:

codex --enable worktrees --worktree "Upgrade the test runner and run its suite"
codex exec --enable worktrees --worktree "Find the flaky test and propose the smallest fix"
codex fork --enable worktrees --worktree <session-id> "Try the lower-risk implementation"

En una bifurcación interactiva, <session-id> es el identificador del chat que muestra /status. La versión 0.154.0 exige indicar ese ID de forma explícita. codex fork --worktree --last no es válido.

El mismo flujo está disponible desde la interfaz de terminal. Escribe /worktree y elige entre continuar la conversación actual en un checkout nuevo, abrir allí una conversación desde cero o explorar los worktrees que Codex ya administra para ese repositorio.

Qué crea Codex

Un worktree administrado es un segundo checkout vinculado al mismo repositorio Git. Imagina el repositorio como un catálogo compartido por dos salas de lectura: cada sala puede tener páginas distintas sobre la mesa, pero ambas consultan los mismos commits y ramas.

Codex crea el checkout a partir del commit al que apunta el HEAD del repositorio de origen, lo deja en estado detached HEAD y lo vincula a la sesión nueva. Detached HEAD significa que el checkout apunta directamente a un commit, en lugar de mover una rama con nombre. El checkout de origen se mantiene como estaba.

Este punto de partida limpio tiene una consecuencia importante: los cambios sin confirmar del checkout original no pasan a la sesión. Tampoco lo hacen los archivos ignorados, como un .env típico o el directorio node_modules. OpenAI documenta la copia mediante .worktreeinclude para worktrees locales administrados por Desktop, pero aclara que ese comportamiento no se aplica a los worktrees creados desde la línea de comandos. En la CLI tendrás que preparar lo que necesite cada tarea.

Si inicias Codex desde un directorio interno del repositorio, el checkout administrado conserva esa ubicación relativa. Por ejemplo, si partes de apps/web, la sesión se abre en el directorio apps/web equivalente del worktree nuevo, siempre que exista en la revisión guardada en el commit.

Flujo práctico: desde el inicio hasta conservar el trabajo

La rutina más segura tiene cinco etapas: partir de un estado limpio, confirmar dónde estás, hacer el trabajo, revisar las pruebas y decidir de forma explícita si conservarlo o descartarlo.

1. Parte del commit correcto

--worktree es un interruptor booleano, no un selector de rama ni de base. El checkout nace del HEAD del repositorio que indiques. Antes de iniciarlo, cambia a la rama base adecuada y haz commit de cualquier modificación del repositorio de origen que la tarea necesite. También puedes usar -C <repo-path> para apuntar Codex a un checkout local concreto.

Abre una sesión nueva cuando la tarea sea independiente. Usa una bifurcación si el segundo intento necesita las decisiones y restricciones de la conversación original. La bifurcación conserva la transcripción en un chat nuevo y traslada el nuevo trabajo a un checkout aislado, de modo que el primer intento queda intacto y se puede comparar.

2. Confirma el checkout antes de editar

Al comenzar, pide a Codex que ejecute pwd, git status --short y git rev-parse --short HEAD. El directorio de trabajo debe ser la ruta administrada, el estado debe estar limpio y el commit debe coincidir con el HEAD de origen que querías usar.

Esta verificación evita el error aburrido que más caro sale: hacer un trabajo excelente sobre la base equivocada.

3. Instala solo lo que necesite este entorno

Un worktree aísla los archivos del checkout. No crea un contenedor, no reserva un puerto, no clona una base de datos ni instala dependencias. Ejecuta el comando habitual de preparación del repositorio dentro del checkout administrado. Si varias sesiones pueden chocar por recursos, asigna a cada una sus propios puertos, bases de datos temporales, directorios de caché y cuentas de prueba.

Este es el límite esencial. Dos diffs de Git perfectamente limpios aún pueden interferir entre sí si ambas sesiones migran la misma base de datos de desarrollo o intentan usar el mismo puerto.

4. Revisa el diff y retoma el hilo correcto

Dentro de la sesión del worktree, /review permite revisar los cambios sin confirmar. Desde otra terminal, primero ejecuta /worktree, elige Browse worktrees, selecciona el checkout y pulsa Copy working directory. Después ejecuta git -C "<worktree-path>" status --short, git -C "<worktree-path>" diff --stat y git -C "<worktree-path>" diff.

No ejecutes codex review --worktree. La versión 0.154.0 rechaza esa combinación de opciones. Revisa el worktree activo desde su propia sesión o dirige las herramientas de revisión habituales a la ruta que copiaste.

Para continuar más tarde, escribe /worktree, elige Browse worktrees, selecciona el checkout administrado y pulsa Resume owner thread. No añadas --worktree a codex resume: al reanudar debes volver al checkout ya vinculado con la sesión, no crear otro.

5. Conserva el cambio antes de limpiar el checkout

Si quieres quedarte con un cambio, ejecuta las pruebas pertinentes, crea un commit dentro del worktree y copia su SHA. Luego, desde el checkout original, usa git cherry-pick <sha> para incorporar ese commit a la rama actual. Haz el cherry-pick antes de eliminar el worktree para que el commit detached ya tenga un destino duradero.

Si el trabajo merece su propia rama de revisión, ejecuta git switch -c codex/<task> en el worktree, crea el commit, súbelo y abre un pull request. Git no permite que la misma rama esté activa al mismo tiempo en el checkout original. Puedes subirla desde el worktree o eliminar ese worktree antes de abrir la rama en otro checkout.

Los worktrees creados desde la CLI no se limpian automáticamente. Cuando el cambio ya esté guardado de forma segura en un commit o descartado a propósito, comprueba que el checkout esté limpio y ejecuta git worktree remove <worktree-path> desde el repositorio de origen. Evita --force. Más adelante, git worktree prune puede borrar registros obsoletos de Git, pero no sustituye la comprobación de si una sesión todavía es propietaria del checkout.

Cómo cambia el presupuesto

La función nativa elimina una capa pequeña pero repetitiva de automatización con shell. Antes de 0.154.0, quien usaba la CLI tenía que crear una ruta, crear una rama o trabajar en modo detached, iniciar Codex en ese directorio, recordar qué chat le correspondía y limpiar después tanto el estado de Git como el de la sesión. Ahora, la nueva opción crea y vincula el checkout en un solo inicio, mientras /worktree ofrece un explorador que conoce el repositorio y una ruta para retomar el trabajo.

Para quien ya tiene una suscripción de Codex, el checkout no conlleva una tarifa adicional publicada. Codex Plus cuesta $20 al mes. Unstoppable, un espacio comercial para agentes que organiza worktrees paralelos, ofrece su plan Pro desde $19 al mes, Business por $29 por usuario y Enterprise por $49 por usuario. Codex nativo ya puede cubrir la tarea concreta de crear un checkout y retomarlo dentro de la suscripción que ya utilizas.

Eso no sustituye todo lo demás que ofrecen esos espacios de trabajo de pago. Los paneles para varios agentes, la asignación de puertos, la preparación compartida del entorno, la agregación de pruebas, el seguimiento de pull requests, las políticas de equipo y los informes de costos siguen estando por encima del checkout básico. Además, las sesiones paralelas consumen la misma cuota de uso de Codex. La lectura económica correcta no es «desarrollo paralelo gratis», sino «una herramienta de orquestación menos si solo la comprabas para aislar archivos».

Para entender la función en el contexto del producto, el análisis de Codex repasa la CLI local y el flujo con agentes. El artículo anterior sobre Codex CLI 0.152.0 explica por qué los límites de cada versión importan al automatizar la terminal.

Siete tareas para worktrees, ordenadas por utilidad

1. Actualizaciones de dependencias arriesgadas

Una persona responsable del mantenimiento puede abrir un worktree para actualizar un framework, un gestor de paquetes o un ejecutor de pruebas. Codex modifica allí los lockfiles y la configuración y ejecuta toda la suite sin ensuciar el desarrollo de la funcionalidad que sigue abierto en el checkout principal. El resultado es una vía de actualización fácil de revisar y descartar, sin guardar cambios en un stash ni revertir modificaciones ajenas.

2. Dos implementaciones rivales de una función

Un líder técnico puede bifurcar la misma conversación de planificación en dos worktrees administrados, pedir a una sesión el parche más pequeño y a la otra un enfoque más estructural, y comparar después el tamaño del diff, las pruebas y el riesgo de migración. Así se elige con evidencia sin que el segundo intento sobrescriba el primero.

3. Diagnóstico de errores junto al desarrollo activo

Una persona de ingeniería de producto que se encuentra a mitad de una función puede abrir un worktree limpio desde el commit al que apunta HEAD para reproducir un error de producción. Codex puede instrumentar, probar y corregir el fallo en ese entorno mientras la función inacabada permanece intacta. Esto reduce los stashes de emergencia y deja un diff de hotfix más limpio.

4. Codemods y refactorizaciones grandes

Un equipo de plataforma puede dedicar un checkout a un cambio amplio de nombres o a una migración de API, ejecutar allí los formateadores y las pruebas, y revisar el conjunto de archivos resultante antes de incorporarlo a la rama principal. El beneficio es la contención: el volumen de cambios generados permanece separado hasta merecer un commit.

5. Una vía para corregir una revisión

Quien abre un pull request puede crear un commit con la base de la revisión, iniciar desde ese estado una sesión aislada de Codex y atender los comentarios sin interrumpir otra rama activa en local. El resultado es una serie enfocada de correcciones que se puede subir desde el worktree cuando esté lista.

6. Tareas de mantenimiento reproducibles

Un perfil de ingeniería de compilación puede usar codex exec --worktree para una tarea concreta, como actualizar archivos generados o investigar una prueba inestable. La ejecución sin interfaz obtiene un checkout limpio de los archivos rastreados y una sesión persistente que se puede revisar más tarde. El beneficio es evitar la contaminación accidental de lo que esté abierto en el árbol de trabajo principal. La condición es que la automatización se ocupe de preparar las dependencias y de limpiar al terminar.

7. Una primera exploración segura del repositorio

Una persona recién incorporada al equipo puede pedir a Codex que trace el mapa de una base de código desconocida y ensayar un pequeño cambio de documentación o pruebas en un worktree administrado antes de tocar el checkout habitual. El beneficio también es psicológico: la exploración tiene un límite visible y se puede descartar con facilidad.

Tres productos que aprovechan lo que aún falta

1. La mejor apuesta: una capa que prepare cada worktree

Construye una herramienta local pequeña que convierta un checkout administrado recién creado en una vía de trabajo ejecutable y sin colisiones. Podría detectar la pila del proyecto, ejecutar la preparación aprobada de dependencias, asignar un puerto, crear una base de datos o un esquema temporal, exponer solo los secretos seleccionados, comprobar el estado del servicio e imprimir el plan de limpieza correspondiente.

La demanda es amplia: git worktree recibe unas 9,900 búsquedas mensuales en Google en EE. UU. y what is a git worktree, otras 590. La función nativa de Codex resuelve la creación del checkout, pero deja pendiente la preparación del entorno de ejecución; por eso, esta es la oportunidad más sólida.

La versión mínima que se puede vender necesita un manifiesto del repositorio, comandos de preparación y desmontaje, reserva de puertos, plantillas para archivos de entorno y una comprobación de estado. El riesgo real es la seguridad. Una herramienta que copie secretos o apunte dos agentes a la misma base de datos puede generar más riesgos de los que elimina. OpenAI también podría incorporar hooks nativos para el ciclo de vida y reducir este espacio.

2. Un panel para vías de trabajo de distintos agentes

Construye un panel de escritorio o terminal que descubra worktrees entre distintos repositorios y herramientas, y que muestre la sesión propietaria, la rama o el estado detached, los archivos modificados, el resultado de las pruebas, el uso de Codex, el pull request, el espacio en disco y una acción segura para retomar o limpiar cada vía.

git worktree claude code recibe unas 480 búsquedas mensuales en Google en EE. UU. y la frase exacta parallel coding agents, 10. Esa segunda consulta es pequeña, pero ya existe una conducta de pago: Unstoppable parte de $19 al mes por un producto que incluye worktrees paralelos para agentes. El comprador es un desarrollador que ya alterna entre Codex, Claude Code y terminales convencionales.

Un MVP puede ser solo de lectura: enumerar los worktrees de Git, vincular los metadatos de sesiones conocidas, ejecutar bajo demanda comandos de estado y pruebas, y ofrecer enlaces directos a cada agente. El obstáculo es la competencia nativa. Codex 0.154.0 ya explora sus propios worktrees administrados, así que el producto tendría que destacar por la visibilidad entre agentes, el estado de ejecución y los informes para equipos.

3. Una puerta de integración y limpieza

Construye un control que se interponga entre una vía terminada por un agente y la rama principal. Verificaría que el estado esté limpio, ejecutaría el conjunto de pruebas obligatorio, detectaría archivos modificados por otros worktrees activos, recomendaría un orden para los cherry-picks y bloquearía cualquier limpieza destructiva mientras quedaran commits sin integrar.

Las preguntas ya aparecen en la demanda de búsqueda: git remove worktree recibe unas 390 búsquedas mensuales en Google en EE. UU.; git worktree vs branch, 320; y git worktree prune, 140. Estas consultas se concentran en el momento en que el trabajo aislado debe convertirse en trabajo compartido.

El MVP consiste en un comando local de Git y un pequeño archivo de políticas. Puede aportar valor sin editar una sola línea de forma automática. El riesgo es la distribución: los clientes de Git y los proveedores de CI pueden añadir las mismas comprobaciones, por lo que una herramienta independiente necesitaría un soporte excelente para distintos agentes de programación y repositorios reales desordenados.

Límites que deben influir en la decisión

Usa worktrees nativos cuando el problema sea aislar archivos. No los confundas con el aislamiento completo del entorno.

Esta versión tampoco ofrece en la CLI un equivalente al botón Handoff de la aplicación Desktop. Llevar el código de vuelta sigue siendo una decisión de Git: crear un commit y aplicar un cherry-pick, subir una rama, o descartar y eliminar. Que el paso sea explícito es saludable. El aislamiento resulta útil precisamente porque nada debería entrar por accidente en el checkout principal.

Tu acción para el lunes: elige una actualización de dependencias que no sea crítica y ejecútala con codex --enable worktrees --worktree; compara el diff y las pruebas desde la ruta copiada del checkout, aplica con cherry-pick únicamente el commit aceptado y elimina después el worktree. Si buscas un flujo fiable de agentes aislados adaptado a tus repositorios, puedo ayudarte a diseñar el sistema para producción.