Codex CLI offers three ways to use Git worktrees: the --worktree flag, the /worktree command, and, since version 0.162.0, three tools that the agent itself can invoke to create and list managed worktrees while your session remains in the original checkout. The feature that enables them, worktrees, is stable and comes enabled by default: there’s nothing to turn on.
We installed 0.162.1 (the current stable, released on October 9th, one day after 0.162.0) and tested each path on a disposable repository. Here’s what each one does, what this version actually added, and a behavior the changelog doesn’t mention: if you don’t name the new tools in your prompt, the agent likely won’t use them.
What is git worktree and why does it matter for AI agents?
A git worktree is a second checkout of the same repository. Each one has its own copy of the files, but they all share a single .git directory: the same commits, the same branches. This lets you have two lines of work open at once without doing stash, without cloning again, and without switching branches over and over.
For code agents, it’s the difference between running one task at a time and running many: each agent works in its own directory, so two agents editing src/ at the same time don’t step on each other.
What changed in Codex CLI 0.162?
Less than “Codex finally has worktrees” suggests, and something more interesting. Comparing 0.161.0 with 0.162.1, side by side:
- Already in 0.161.0: the
--worktreeflag, the/worktreecommand, and theworktreesfeature, enabled by default. - New in 0.162.0 (PR #50148): three tools the model can invoke:
create_worktree,get_worktree_creation_status, andlist_worktrees. Now the agent can create a worktree in the background and associate it with the current task, while that task’s working directory stays where it was.
That is, the change isn’t for you, the human, who already had a flag. It’s for the agent: now it can decide it needs an isolated checkout, create one, and keep working.
Do you have to enable worktrees in Codex CLI?
No. The changelog says the tools work “when the worktrees feature is enabled”, which sounds like a hidden switch. It’s not:
codex features list | grep worktrees
In 0.162.1 this prints worktrees stable true. The same already happened in 0.161.0.
The other requirement is that the project be trusted: according to the PR, creation is rejected on projects explicitly marked as untrusted. Codex asks if you trust a folder the first time you open it; answer yes.
To install or upgrade to the current stable:
npm install -g @openai/codex@0.162.1
How do you start a Codex CLI session in a worktree?
Launch Codex with the flag from inside your repository:
codex --worktree
The help text describes it as “Run the session in a new managed Git worktree”. The same flag exists in codex exec for non-interactive runs. Inside an already-open session, /worktree does the same.
In our test, the worktree ended up at ~/.codex/worktrees/<id>/repo: a random short identifier plus the repository name. An uncommitted change we left in the original checkout did not pass to the worktree: only committed work is carried over.
Why does the worktree end up in detached HEAD?
Because Codex doesn’t create a branch for it. The worktree points directly to the current commit in detached HEAD state, so your branch list stays clean. If you later want to keep the work, you create a branch from that worktree like you would with any checkout.
How does the agent create its own worktrees?
You ask it to, and the way you ask matters. This was the most useful finding from the test.
With a generic prompt (“Create a worktree to try adding a LICENSE file”), the agent completely ignored the new tools. It ran a normal git worktree add -b try-license-2 /private/tmp/..., asked for the usual approval for shell commands, and created a real branch in /tmp. That’s the manual recipe, not the managed function.
When we asked it to list its tools with “worktree” in the name, it said it had none. The tools exist, but they don’t load until something asks for them by name. They live under the codex_tui namespace:
codex_tui.create_worktreecodex_tui.get_worktree_creation_statuscodex_tui.list_worktrees
Naming them works. This 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.
produced a managed worktree at ~/.codex/worktrees/<id>/repo, in detached HEAD, without any shell or Git commands. Creation is asynchronous: create_worktree returns pending with an operation ID, and get_worktree_creation_status returns created when the checkout is ready. The session stayed in the original repository the whole time.
Two things worth knowing:
- No approval request. Unlike the
git worktree addpath,create_worktreeran without asking. It only creates a checkout and doesn’t modify your files, but if you work with a strict approval policy, note that the agent can do it on its own. - Default base branch. According to the PR, the worktree starts from the remote’s default branch, unless the agent specifies a concrete
ref. If you cloned an empty repository, Git may never have recorded that branch;git remote set-head origin --autofixes it.
What happens to worktrees when you finish?
Archive the session (/archive inside Codex, or codex archive from the terminal) and its managed worktree goes with it: we saw it disappear from git worktree list. If you want to review how session archiving works, we explain it in Session management in Codex CLI.
That’s the clearest difference from the manual path: the two worktrees the agent created in /tmp with plain Git stayed there, along with their branches, until we manually deleted them with git worktree remove and git branch -D.
Worktrees managed by Codex or your own git worktree scripts?
If you already run agents in parallel with your own git worktree add scripts, here’s what the managed version solves for you:
| Your own script | Managed by Codex | |
|---|---|---|
| Location | wherever you put it | ~/.codex/worktrees/<id>/repo |
| Branch | typically creates one | detached HEAD, no branch |
| Trust control | none | rejected on untrusted projects |
| Cleanup | manual (git worktree remove, git branch -D) |
deleted when you archive the session |
| Agent can create it mid-task | only with shell commands | yes, with create_worktree, without leaving the task directory |
One gap: OpenAI’s worktrees documentation covers the ChatGPT desktop app (Handoff, the .worktreeinclude file to copy ignored files like .env, the 15-worktree cleanup limit) and clarifies that .worktreeinclude applies to worktrees managed by the desktop app. As of the time this note was published (October 13th, 2026), it didn’t document --worktree, /worktree, or the new CLI tools, so we don’t assume that behavior carries over.
What else does Codex CLI 0.162 bring?
/copyto navigate and copy blocks from history,Ctrl+Insertto copy a selection, andtui.mouse_scroll_speedto adjust scroll speed.- Pin tasks in the agent Command Center with the
pkey. - Clickable URLs in approval headers, questions, MCP prompts, warnings, and banners, even when they span more than one line.
- 0.162.1 fixed a TUI bug with multi-line questions and startup errors when a background server’s feature configuration didn’t match the CLI defaults.
What about you? How many agents do you run at once on the same repository, and how do you keep them from stepping on each other?
- With worktrees managed by the tool (Codex, Claude Code…)
- With my own git worktree scripts
- One agent at a time, no parallelism
- I prefer another option (tell us which)
Comment below or, if this article reached you by email, reply directly to the email: your response gets published here.
Related: Return to your agent’s session from the graph: GitLens 19 ties Claude Code to each worktree