Codex CLI 0.162 lets the model create git worktrees mid-task

The October 8, 2026 release of Codex CLI 0.162.0 shipped a small feature with outsized consequences for how coding agents manage code: the model can now create a git worktree on its own initiative, partway through a task, without disturbing the checkout it was started in. According to a code-level analysis published on dev.to, the changelog entry is brief — new tools for creating and listing managed git worktrees from trusted local projects — but the design decisions underneath are worth unpacking. The post's author notes the findings come from reading the release's source rather than running it.

What shipped

The pull request behind the feature names three tools: create_worktree, get_worktree_creation_status and list_worktrees. They become available when the worktrees feature is enabled (registered as stable and on by default, per the dev.to walkthrough), the project is trusted, and attachment storage is available. Two situations are refused outright: projects explicitly marked untrusted, and ephemeral side conversations, which cannot retain worktree attachments. A 0.162.1 patch followed on October 9 with two bug fixes.

An asynchronous checkout

create_worktree does not block until the new checkout exists. Its schema requires an async opt-in and accepts one optional ref, and it answers immediately with an operation ID the model then polls through the status tool. Creation has three outcomes — pending, created, and a registration failure in which the checkout exists on disk but could not be attached to the task. The tool descriptions coach the model on both edge cases: do not fire off a duplicate creation while one is pending, and if registration fails, work with the paths already returned rather than making another worktree.

Where the tree lands

Left to its defaults, the new tree is based on the repository's remote default branch — not the branch you happen to be on — resolved from cached remote refs without a network fetch, with fallbacks through the usual main and master candidates before the tool gives up. The tree is placed under a worktrees directory inside the Codex home folder (overridable via a setting), inside a randomly named bucket directory, then a folder named after the repository. Under the hood it is a detached git worktree add followed by a hard reset to the target commit: no branch is created, and uncommitted changes in your checkout are not carried over.

The directory that doesn't move

The defining constraint is that the task's working directory never changes. Every command the model wants to run against the new tree has to name it explicitly — git -C, a chained cd, or absolute paths — because relative paths still resolve against the original checkout, the one holding your dirty files. Permissions follow the same split: since the new tree sits outside your repository, the sandbox's workspace-write access does not cover it, and writing there requires the model to request filesystem access or a configured writable root. list_worktrees is also narrower than its name suggests, listing only active or archived worktree attachments for the current task — not trees from other tasks or ones you created by hand — and it instructs the model to treat returned paths as data rather than as instructions.

There is a separate entry point if you want the agent to start inside a fresh tree: a global --worktree flag for new interactive sessions and certain exec and fork commands, though not for resuming an existing session. In other words, you choose at launch with the flag, or the model chooses mid-task with the tool.

Cleanup is on you

According to dev.to, the CLI builds its worktree settings with automatic cleanup disabled, and the retention policy in OpenAI's documentation — keeping the fifteen most recent worktrees — belongs to the ChatGPT desktop app, not the CLI. Nothing prunes on your behalf, and since the checkout has a detached HEAD and no branch, the only way to keep work done there is to commit it to a branch.

Why it matters

This release formalizes a pattern that agent workflows have been reaching for: side work in an isolated checkout while the main working tree, and its uncommitted state, stays untouched. Reproducing a bug on the default branch while a half-finished change sits in place no longer requires restarting a session or stashing anything. It also keeps the permission model honest: the agent gets a clean copy to experiment in, but writes outside your repository still go through explicit approval. The trade-offs are real — detached trees with no branch and no automatic cleanup mean silently lost work if nobody commits — but as a template for how coding agents should handle working directories, it is a notable step.