What Is a Worktree in Codex? A Practical Guide

Say you’re editing the settings screen and want Codex to fix a date formatting bug. Start the bug fix in a worktree based on main. Codex can edit and test the fix in its own folder while your editor stays on the settings branch. When the fix is ready, you can review it and open a pull request from the worktree.

Local vs. Worktree in Codex

• Local uses the project folder you already have open. Choose it when Codex needs to work directly with the edits, dependencies, or running dev server in that checkout.
• Worktree gives the chat its own checkout. Choose it for an independent fix, an experiment, or a second Codex chat that will edit the same repo in parallel.

A branch is a named pointer to a commit. A worktree is the folder where you edit files. Two worktrees can start from the same commit, even though Git normally lets a named branch be checked out in only one worktree at a time. For more on the distinction, see Git worktree vs. branch.

How to start a Codex chat in a worktree

1. In Codex in the ChatGPT desktop app, start a new chat in a project that lives in a Git repository.
2. Choose Worktree under the composer. Select a local environment if you have a setup script for the project.
3. Choose the starting branch. Pick main for a fix that doesn’t need your feature branch, or choose the feature branch if Codex needs that code. Codex can carry over uncommitted changes from the branch you select, so choose a clean starting point if you want only committed code.
4. Send your prompt. Codex creates the checkout when the chat starts. Use the chat’s Open menu or integrated terminal to inspect and test the work in that folder.

If the app runs in Local but fails to start in the worktree, check for missing dependencies or an ignored .env file. A local environment setup script can install dependencies when the checkout is created. To copy an ignored file into a new local Codex-managed worktree, put its path, such as .env.local, in a .worktreeinclude file at the repository root. Run parallel dev servers on different ports if both instances need to stay up.

How to keep the changes

Codex starts a managed worktree in detached HEAD. Git points directly to the starting commit, so the chat can work without taking over the starting branch. If you commit in this state, a named branch won’t point to your new commits until you create one.

• Keep working in the separate folder. Choose Create branch here in the chat header. Review the diff, run your checks, then commit and push the branch when you’re ready for a pull request. If Codex already made commits on detached HEAD, the new branch starts at the current commit and keeps them reachable.
• Continue in your usual project folder. Choose Hand off in the chat header and select Local. Codex moves the chat and its changes into your local checkout. Use this too if Git says the branch is already checked out in the worktree.

Codex can remove managed worktrees when you archive chats or hit the configured retention limit. It saves a snapshot and offers to restore it when you reopen the chat. For changes you plan to keep, save them on a branch before cleaning up. See OpenAI’s worktree documentation for the retention settings and restore behavior.

Find and review Codex worktrees on your Mac

Run git worktree list from your usual repo folder to see the checkout paths and spot entries marked (detached HEAD). If you have several projects open, Orchard puts their worktrees in one Mac window so you can see where Codex is still working, review diffs, and find commits that haven’t landed, including commits made on a detached HEAD.

Frequently asked questions