Codex CLI ofrece tres formas de usar worktrees de Git: el flag --worktree, el comando /worktree y, desde la versión 0.162.0, tres herramientas que el propio agente puede invocar para crear y listar worktrees administrados mientras tu sesión sigue en el checkout original. La función que las habilita, worktrees, es estable y viene activada por defecto: no hay nada que encender.
Instalamos la 0.162.1 (la estable actual, publicada el 9 de octubre, un día después de la 0.162.0) y probamos cada camino sobre un repositorio desechable. Aquí tienes qué hace cada uno, qué agregó realmente esta versión y un comportamiento que el changelog no menciona: si no nombras las nuevas herramientas en tu prompt, lo más probable es que el agente no las use.
¿Qué es git worktree y por qué importa para los agentes de IA?
Un git worktree es un segundo checkout del mismo repositorio. Cada uno tiene su propia copia de los archivos, pero todos comparten un único directorio .git: los mismos commits, las mismas ramas. Eso te permite tener dos líneas de trabajo abiertas a la vez sin hacer stash, sin clonar de nuevo y sin cambiar de rama una y otra vez.
Para los agentes de código, es la diferencia entre ejecutar una tarea a la vez y ejecutar varias: cada agente trabaja en su propio directorio, así que dos agentes editando src/ al mismo tiempo no se pisan.
¿Qué cambió en Codex CLI 0.162?
Menos de lo que sugiere un “Codex por fin tiene worktrees”, y algo más interesante. Comparando la 0.161.0 con la 0.162.1, lado a lado:
- Ya estaba en la 0.161.0: el flag
--worktree, el comando/worktreey la funciónworktrees, activada por defecto. - Nuevo en la 0.162.0 (PR #50148): tres herramientas que el modelo puede invocar:
create_worktree,get_worktree_creation_statusylist_worktrees. Ahora el agente puede crear un worktree en segundo plano y asociarlo a la tarea actual, mientras el directorio de trabajo de esa tarea se queda donde estaba.
Es decir, el cambio no es para ti, el humano, que ya tenías un flag. Es para el agente: ahora puede decidir que necesita un checkout aislado, crearlo y seguir trabajando.
¿Hay que activar los worktrees en Codex CLI?
No. El changelog dice que las herramientas funcionan “cuando la función de worktrees está habilitada”, lo que suena a un interruptor oculto. No lo es:
codex features list | grep worktrees
En la 0.162.1 esto imprime worktrees stable true. Lo mismo ya ocurría en la 0.161.0.
El otro requisito es que el proyecto sea de confianza: según el PR, la creación se rechaza en proyectos marcados explícitamente como no confiables. Codex te pregunta si confías en una carpeta la primera vez que la abres; responde que sí.
Para instalar o actualizar a la estable actual:
npm install -g @openai/codex@0.162.1
¿Cómo inicias una sesión de Codex CLI en un worktree?
Lanza Codex con el flag desde dentro de tu repositorio:
codex --worktree
El texto de ayuda lo describe como “Run the session in a new managed Git worktree”. El mismo flag existe en codex exec para ejecuciones no interactivas. Dentro de una sesión ya abierta, /worktree hace lo mismo.
En nuestra prueba, el worktree quedó en ~/.codex/worktrees/<id>/repo: un identificador corto aleatorio más el nombre del repositorio. Un cambio sin commitear que dejamos en el checkout original no pasó al worktree: solo se lleva el trabajo commiteado.
¿Por qué el worktree queda en detached HEAD?
Porque Codex no crea una rama para él. El worktree apunta directamente al commit actual en estado detached HEAD, así que tu lista de ramas queda limpia. Si después quieres conservar el trabajo, creas una rama desde ese worktree como harías con cualquier checkout.
¿Cómo crea el agente sus propios worktrees?
Se lo pides, y la forma de pedirlo importa. Este fue el hallazgo más útil de la prueba.
Con un prompt genérico (“Create a worktree to try adding a LICENSE file”), el agente ignoró por completo las nuevas herramientas. Ejecutó un git worktree add -b try-license-2 /private/tmp/... normal, pidió la aprobación habitual para comandos de shell y creó una rama real en /tmp. Esa es la receta manual, no la función administrada.
Cuando le pedimos que listara sus herramientas con “worktree” en el nombre, respondió que no tenía ninguna. Las herramientas existen, pero no se cargan hasta que algo las pide por su nombre. Viven bajo el espacio de nombres codex_tui:
codex_tui.create_worktreecodex_tui.get_worktree_creation_statuscodex_tui.list_worktrees
Nombrarlas funciona. Este prompt:
Use your create_worktree tool, not the shell or git, to create a worktree for adding a LICENSE file. Then check its status with get_worktree_creation_status, and finally call list_worktrees.
produjo un worktree administrado en ~/.codex/worktrees/<id>/repo, en detached HEAD, sin ningún comando de shell ni de Git. La creación es asíncrona: create_worktree devuelve pending con un identificador de operación, y get_worktree_creation_status devuelve created cuando el checkout está listo. La sesión se quedó todo el tiempo en el repositorio original.
Dos cosas que conviene saber:
- No hay solicitud de aprobación. A diferencia de la vía
git worktree add,create_worktreese ejecutó sin preguntar. Solo crea un checkout y no modifica tus archivos, pero si trabajas con una política de aprobaciones estricta, ten en cuenta que el agente puede hacerlo por su cuenta. - Rama base por defecto. Según el PR, el worktree parte de la rama por defecto del remoto, salvo que el agente indique un
refconcreto. Si clonaste un repositorio vacío, es posible que Git nunca haya registrado esa rama;git remote set-head origin --autolo resuelve.
¿Qué pasa con los worktrees cuando terminas?
Archiva la sesión (/archive dentro de Codex, o codex archive desde la terminal) y su worktree administrado se va con ella: lo vimos desaparecer de git worktree list. Si quieres repasar cómo funciona el archivado de sesiones, lo explicamos en Session management en Codex CLI.
Esa es la diferencia más clara con la vía manual: los dos worktrees que el agente creó en /tmp con Git a secas se quedaron ahí, junto con sus ramas, hasta que los borramos a mano con git worktree remove y git branch -D.
¿Worktrees administrados por Codex o tus propios scripts de git worktree?
Si ya ejecutas agentes en paralelo con tus propios scripts de git worktree add, esto es lo que la versión administrada resuelve por ti:
| Tu propio script | Administrado por Codex | |
|---|---|---|
| Ubicación | donde lo pongas | ~/.codex/worktrees/<id>/repo |
| Rama | normalmente crea una | detached HEAD, sin rama |
| Control de confianza | ninguno | se rechaza en proyectos no confiables |
| Limpieza | manual (git worktree remove, git branch -D) |
se elimina al archivar la sesión |
| El agente puede crearlo a mitad de tarea | solo con comandos de shell | sí, con create_worktree, sin salir del directorio de la tarea |
Un vacío: la documentación de worktrees de OpenAI cubre la app de escritorio de ChatGPT (Handoff, el archivo .worktreeinclude para copiar archivos ignorados como .env, el límite de limpieza de 15 worktrees) y aclara que .worktreeinclude aplica a los worktrees administrados por la app de escritorio. Al momento de publicar esta nota (13 de octubre de 2026), no documentaba --worktree, /worktree ni las nuevas herramientas del CLI, así que no damos por hecho que ese comportamiento se traslade.
¿Qué más trae Codex CLI 0.162?
/copypara navegar y copiar bloques del historial,Ctrl+Insertpara copiar una selección ytui.mouse_scroll_speedpara ajustar la velocidad del scroll.- Fijar tareas en el Command Center de agentes con la tecla
p. - URLs clicables en encabezados de aprobación, preguntas, prompts de MCP, advertencias y banners, incluso cuando ocupan más de una línea.
- La 0.162.1 corrigió un fallo de la TUI con preguntas de varias líneas y errores de arranque cuando la configuración de funciones de un servidor en segundo plano no coincidía con los valores por defecto del CLI.
¿Y tú? ¿Cuántos agentes ejecutas a la vez sobre el mismo repositorio, y cómo evitas que se pisen?
- Con worktrees administrados por la herramienta (Codex, Claude Code…)
- Con mis propios scripts de git worktree
- Un agente a la vez, sin paralelismo
- Prefiero otra opción (cuéntanos cuál)
Comenta abajo o, si este artículo te llegó por correo, responde directamente al email: tu respuesta se publica aquí.
Relacionado: Volver a la sesión de tu agente desde el grafo: GitLens 19 ata Claude Code a cada worktree