teebe › Guides › Codex worktrees

Codex worktrees: how the Codex app isolates parallel work

How the Codex app uses git worktrees to keep parallel chats out of each other's way, and where they end up on disk.

When you start a new chat in the Codex app, you can put it in a Codex worktree: a separate git checkout, isolated from your main working copy, so that chat's edits don't collide with whatever else you're doing in the repo. This is the same underlying mechanism as plain git worktree, wired up by Codex so you don't have to run the commands yourself. This guide covers where Codex puts worktrees, the two kinds it manages, how to hand off between them, cleanup limits, and what to do from the CLI if you'd rather drive it by hand.

Starting a chat in a worktree

In the new chat view, choose Worktree, pick a starting branch, and submit your prompt. Codex creates a git worktree from that branch and runs the chat inside it. Two things worth knowing up front:

• The worktree starts in a detached HEAD state, it is not checked out to a branch yet. Click Create branch here in the chat header when you want to turn it into a real branch you can push.
• Git only allows a given branch to be checked out in one worktree at a time, so if a branch is already active elsewhere, Codex (like plain git) can't check it out again in a second worktree.

Where Codex puts worktrees on disk

By default, Codex creates worktrees under $CODEX_HOME/worktrees. If you want them somewhere else, change the location in Settings > Worktrees > Worktree root. Because this is separate from your project directory, it's easy to lose track of which folder belongs to which chat, especially once you have several running.

Managed vs permanent worktrees

Codex distinguishes two kinds of worktree:

• Managed worktrees: lightweight, created automatically per chat, and usually hold one chat each.
• Permanent worktrees: created from the three-dot menu on a project in the sidebar. They're never auto-deleted and can host multiple chats at once, which makes them a better fit for a long-running branch you keep coming back to.

Handing off between Local and Worktree

A chat can be moved between your local checkout and a worktree with the Hand off control. A couple of details affect what actually shows up when you hand off:

• Gitignored files (like .env) are not carried over automatically. List the ones you need in a .worktreeinclude file (gitignore syntax) to have them copied in.
• Codex automatically copies an ignored AGENTS.override.md into managed worktrees, so per-worktree agent instructions travel with the chat.
• The Open button in the chat header opens your IDE directly at the worktree's path.

Cleanup and limits

Codex keeps up to 15 managed worktrees by default (configurable). Worktrees belonging to pinned or in-progress chats, and all permanent worktrees, are excluded from auto-deletion. When Codex does clean one up, either because you archived the chat or it needs space, it saves a snapshot first. If you reopen that chat later, the worktree is restored from the snapshot.

Codex CLI and plain git worktrees

The worktree behavior above belongs to the Codex app. The Codex CLI docs don't document worktree-specific flags or automatic worktree creation. If you drive Codex from a terminal, you get equivalent isolation by driving git yourself:

git worktree add ../repo-task -b task
cd ../repo-task
codex

That's a plain git worktree add followed by cd and codex, one branch, one directory, no collision with your main checkout. See the git worktree cheat sheet for the rest of the commands (list, remove, lock, prune) if you're managing these by hand.

See every worktree in one window

The blind spot with app-managed worktrees is that they pile up somewhere under $CODEX_HOME/worktrees, in detached HEAD, and it's genuinely hard to tell from Finder or a terminal which folder belongs to which chat, or what any of them actually changed.

teebe is a native macOS git worktree GUI built for exactly this. Add your repo once and every worktree shows up in one list, including the ones Codex created for you. Pick one and you get a live file tree that badges the instant Codex edits a file, with no manual refresh. Press Space on a changed file to peek its diff inline, or open it in whatever editor you already use. It also lists ahead/behind counts and can add or remove worktrees itself, and it auto-detects worktrees created or removed externally, so a worktree Codex creates (or deletes) shows up without you doing anything. teebe doesn't edit code, run agents, or touch git history, it's the navigator, not the driver. If you use Claude Code too, the Claude Code worktrees guide covers the same idea there, and every git worktree GUI for Mac, compared if you want to see the alternatives.

Frequently asked questions

Where are Codex worktrees stored?

By default under $CODEX_HOME/worktrees. You can change the location in Settings > Worktrees > Worktree root.

Why is my Codex worktree in detached HEAD?

New Codex worktrees start detached from the branch they were created from, not checked out to a branch. Click Create branch here in the chat header to turn it into a real branch.

Does Codex delete worktrees?

Codex keeps up to 15 managed worktrees by default and can auto-delete older ones when you archive a chat or it needs space, after saving a snapshot you can restore by reopening the chat. Permanent worktrees, and worktrees of pinned or in-progress chats, are never auto-deleted.

Can two chats share a worktree?

Yes, but only if it's a permanent worktree, created from the three-dot menu on a project in the sidebar. Managed worktrees are usually one chat each.

Free · open source · macOS 14+. Back to teebe.io →