This article was converted by SimpRead; original source: www.boboidea.com
Based on OpenAI’s official Codex documentation, this guide explains the role of worktrees in the Codex app, the Handoff workflow, branch restrictions, and cleanup mechanisms—helping you safely advance multiple tasks in parallel.
If you’re already using the Codex app for code modification, debugging, or automation, you’ll almost certainly encounter the concept of Worktree sooner or later. Its value lies not in “adding yet another Git term,” but in enabling Codex to work concurrently within the same project while minimizing disruption to your current local checkout.
This article synthesizes OpenAI’s official documentation and focuses on answering four key questions:
What exactly is a worktree?
Why does Codex need it?
How do you switch between Local and Worktree?
And what limitations should you be aware of before using it?
What Are Codex Worktrees?
According to OpenAI’s official documentation, worktrees in the Codex app are built upon Git worktrees. Fundamentally, they create an additional working copy based on the same repository.
This copy has two critical characteristics:
- It maintains its own independent file workspace, allowing separate code modifications.
- It shares
.gitmetadata with the original repository, meaning it remains part of the same Git repository system.
This means you can preserve your local development context while letting Codex operate concurrently in a separate, isolated copy.
OpenAI explicitly states: Within a Git repository, Codex automations run on dedicated background worktrees to avoid conflicts with your ongoing work.
Understanding Three Key Terms First
The official documentation introduces three terms worth memorizing upfront:
Local checkout: The local project directory you created and are actively using.Worktree: An additional working copy derived by Codex from your local project.Handoff: The process of moving a thread from Local to Worktree—or back again from Worktree to Local.
In one sentence: Local functions like the foreground; Worktree acts as the background; Handoff is the safe switching mechanism between them.
Why Use Worktrees?
OpenAI’s rationale is straightforward—we’ve paraphrased it here in more familiar developer terms:
1. Enable Codex to work in parallel without disrupting your current environment
You may have an IDE open, a local development server running, database connections active, and uncommitted changes pending. If Codex modified files directly in your current directory, interference would be highly likely.
Worktrees isolate Codex’s actions.
2. Separate background tasks from foreground tasks
Worktrees are ideal when you want Codex to continue working in the background on tasks such as:
- Pursuing a complex debugging thread
- Running automated health checks
- Handling changes on another feature branch
- Preparing modifications in advance for later review
3. Bring threads back to Local when needed
When you’re ready to thoroughly review, integrate, or test, you can hand off the thread back to Local—and continue in your familiar IDE and local runtime environment.
This is far safer than mixing everything together in your current directory from the start.
How to Start Using Worktrees in the Codex App
Per the official documentation, the setup process is simple:
- When starting a new thread, select
Worktreebelow the input box. - Choose the branch to serve as the starting point.
- Submit the task—Codex will create a worktree based on that branch.
- Later decide whether to remain in the worktree or hand off back to Local.
Two implementation details deserve special attention.
You Can Launch From a Branch With Local Uncommitted Changes
The official documentation confirms that the starting branch may be:
main/master- A feature branch
- Your current branch—including unstaged local changes
This is highly practical—it means worktrees aren’t limited to “clean” repositories; they also support splitting off parallel tasks directly from your current working state.
Default State Is Detached HEAD
After creation, Codex places the worktree in a detached HEAD state by default.
Benefits include:
- Avoiding accidental pollution of existing branches from the outset
- Enabling lightweight creation of multiple worktrees
- Better alignment with treating each worktree as an independent task environment
If you later decide to persist those changes long-term, you can simply create a branch inside the worktree.
How to Switch Between Local and Worktree
This section contains what we consider the most valuable part of the official documentation—not Git theory, but real-world collaboration patterns in Codex.
OpenAI’s guidance boils down to two recommended paths.
Path 1: Complete the Task Entirely Within the Worktree
If you can validate results directly inside the worktree—for example:
- Dependencies are already installed
- Local environment scripts initialize successfully
- The task doesn’t require your primary development environment
Then staying in the worktree is the simplest approach.
The official documentation notes that in this case you can:
- Create a branch directly on the current worktree
- Commit code
- Push to the remote repository
- Initiate a PR on GitHub
Path 2: Hand Off the Thread Back to Local
If you prefer to bring the task into the foreground—for instance:
- You want to inspect diffs carefully in your daily IDE
- You need to verify behavior using your existing development services
- Your application supports only one running instance at a time
Then handing off the thread back to Local is appropriate.
OpenAI emphasizes that Handoff automatically handles underlying Git operations, ensuring both the thread context and associated code migrate safely.
Moreover, each thread remains persistently linked to the same worktree. So if you later move the thread back to Worktree, Codex resumes work in that original background environment—not a newly created one.
Common Use Cases
If you’re unsure whether worktrees suit your needs, consider these frequent scenarios:
- You’re developing locally while wanting Codex to handle another task in parallel
- You don’t want automation tasks touching your current working directory directly
- You’d like to delegate time-intensive tasks—like review, debugging, or refactoring—to the background
- You need to explore multiple directions concurrently within the same repository
In short: If you ever worry “Will Codex’s changes affect my current development context?”, worktrees are likely your best first choice.
Important Notes
Please read this section carefully—these are common pitfalls.
1. The Same Branch Cannot Be Checked Out Simultaneously in Two Worktrees
The official documentation explicitly states: Git prohibits checking out the same branch in two worktrees simultaneously.
So if you’ve already committed changes to feature/a within a worktree, you must not also check out feature/a in Local—otherwise you’ll encounter errors like:
fatal: 'feature/a' is already used by worktree at '<WORKTREE_PATH>'
Correct approaches typically include:
- Keep working in the background environment (i.e., stay in the worktree)
- Use Handoff to return to Local—rather than forcibly checking out the same branch in both locations
2. Files Listed in .gitignore Are Not Carried Over During Handoff
The official documentation highlights this clearly: Because Handoff relies on Git operations, any files ignored by .gitignore won’t be automatically transferred during thread switching.
This implies that if your runtime depends on locally generated files, caches, or temporary configurations, you’ll need to account for them manually before switching.
3. Worktrees Can Consume Significant Disk Space
Each worktree carries its own full set of repository files, dependencies, caches, and build artifacts—disk usage adds up quickly.
Per the official documentation, Codex retains the 15 most recent Codex-managed worktrees by default and attempts to auto-clean older ones.
4. Auto-Cleanup Is Not Blind Deletion
The official documentation specifies that the following types of worktrees are generally not auto-deleted:
- Those bound to pinned conversations
- Those associated with active threads
- Permanent worktrees
Before deletion, Codex saves a snapshot—allowing restoration when reopening related conversations.
Advanced Topic: Difference Between Codex-Managed and Permanent Worktrees
By default, threads use Codex-managed worktrees. These are designed to be disposable, lightweight, and recyclable—typically one thread maps to one background copy.
If you need a long-lived environment, the official documentation recommends creating a permanent worktree. Unlike temporary background worktrees, permanent ones won’t be auto-deleted, and multiple threads can originate from the same permanent worktree.
In brief:
- For temporary tasks, automation, or parallel exploration → prefer Codex-managed worktrees
- To maintain a persistent, independent development copy → consider permanent worktrees
One-Sentence Summary
The core value of Codex Worktrees isn’t “just another directory”—it’s about cleanly separating AI agent execution (background) from your human-led development (foreground). Once you understand Local, Worktree, Handoff, and branch restrictions, you can confidently let Codex advance tasks in parallel.
References
- OpenAI Official Documentation (Codex Worktrees): Worktrees | ChatGPT Learn