Codex Gets Native Worktree Tools

Ethan Park

Because Codex 0.154.0 only gave you a worktree flag and a slash command, the agent itself still had no clean way to isolate its own work. Thanks to Jellypod to help make this daily show a reality. Today is about the change that closes that gap: pull request 50148, merged into main on October 2, 2026, commit e7ea5f4 by bc-openai. It adds three Model Context Protocol tools to the Codex TUI: create_worktree, get_worktree_creation_status, and list_worktrees.

Maya

Let's separate that from what we covered earlier. In 0.154.0, a human typed the worktree flag or the slash command to isolate a task. This pull request makes worktree management something the model can call as structured tools. And before this, the options were limited. The agent either ran raw shell commands like git worktree add, which risks path conflicts, leaves no attachment state, and can hit sandbox approval prompts, or it worked directly inside your active working copy.

Ethan Park

Here's the mechanism. The tools show up only when features.worktrees is enabled, and only for a trusted local Git repository where attachment storage is available. Both embedded TUI sessions and background daemon sessions, the ones started with codex daemon, are supported. Creation is asynchronous. The model calls create_worktree, which kicks off the work in the background, then polls get_worktree_creation_status until it's ready, and uses list_worktrees to enumerate what exists and find the path.

Maya

The detail I'd underline is that create_worktree does not move the parent task. The parent task's working directory and execution environment stay unchanged, and uncommitted changes on your current branch are left alone. So you can have half-finished edits in your tree, ask the agent to go reproduce something elsewhere, and keep typing in your editor.

Ethan Park

On branching, if the model passes no ref, the worktree defaults to the repository's remote default branch, so origin/main or origin/master depending on the repo. If you pass an explicit ref parameter, that wins.

Maya

Setup first. In your config.toml under the .codex directory in your home folder, add a features table and set worktrees equal to true. Then check the preconditions: the project root has to be a trusted Git repository under your workspace trust policy, and attachment storage has to be initialized.

Ethan Park

Then the prompt does the work. Something like: reproduce this issue on origin slash release v2 without touching my current branch. The agent should call create_worktree with ref set to that branch, poll the status tool, and then call list_worktrees to discover the path it should operate in. It's a good fit for risky test refactors, reproducing a bug against a clean branch, or running concurrent builds, anything where you don't want the agent churning your active files.

Maya

Persistence matters here too. Created worktrees are attached to the requesting task or thread, and the ownership and attachment metadata survive session restarts and resumes. If your session drops, codex resume re-attaches the existing worktree to the active task. It does not re-run creation.

Ethan Park

Now the guardrails. Explicitly untrusted projects reject worktree tool calls outright, so you need to approve workspace trust first. Ephemeral side conversations are blocked from creating worktrees, because ephemeral sessions have no persistent attachment storage. If several calls fire concurrently, the engine reuses the pending creation operation instead of making duplicates.

Maya

One more that affects people with MCP setups. Codex rejects configured third party MCP servers whose exported tool names collide with the TUI worktree namespace. So if you wrote your own server that exposes something called list_worktrees, check that before you upgrade, because Codex will reject that server.

Ethan Park

And on timing: this landed on main on October 2 and is shipping through the 0.162.0 alpha builds, alpha 1 through alpha 10. The latest stable release is 0.160.0, so stable users get it in the next general release. If you want it today, you're on an alpha. Treat it as pre release behavior.

Maya

A few smaller changes from the same October 1 and 2 window. First, tui.mouse_scroll_speed, from pull request 50209. The default wheel scroll drops from three rows per event to one. It accepts float values: 3.0 restores the old speed, and 0.5 scrolls one row every two events by accumulating sub rows.

Ethan Park

Pull request 50052 helps with lost context. When a turn fails, completes, or is interrupted, an unsent answer in the prompt is recovered into the composer, now prepended with the question title as a Markdown blockquote, bounded to 512 bytes. You see what you were answering.

Maya

Pull request 50219 targets startup hangs. Tmux option probes now run on a worker thread with a one second timeout and a 4 KiB read cap, and hung commands get killed and reaped. Separately, pull request 50215 adds Ctrl+Insert for copying transcript and composer selections, matching Windows Terminal's default behavior.

Ethan Park

Also in this window: the command center task rename field now supports Vim normal and insert modes, with horizontal scrolling and newlines stripped, from pull request 50216. Stable completed Markdown tables now enter terminal scrollback during streaming instead of waiting for the end, per pull request 50207, and they reflow if trailing link definitions arrive. And pull request 50199 keeps your account email in the slash status output by re fetching it after account updates, with a 30 second timeout.

Maya

If you try the worktree tools this week, start with a throwaway repo, enable the feature flag, and watch whether the agent actually polls the status tool before it touches the path.