Introduction
Codex Git Worktree enables developers to run separate Codex tasks inside independent Git working trees. Each task gets its own file checkout and working directory, while sharing commit objects and repository metadata. This design allows multiple development tasks to advance in parallel without file conflicts or code overwrites. OpenAI’s official documentation defines Codex Git Worktree as Codex’s backend isolation environment. It uses detached HEAD mode by default and relies on the Handoff mechanism to safely transfer work between local checkouts and remote worktree environments.
This guide breaks down the definition, core distinctions, operational workflows, command reference, branch strategy, ignored file configuration, cleanup routines and troubleshooting for Codex Git Worktree. Readers will learn how to safely split work into parallel tasks, isolate experimental changes, and transfer completed work between backend worktrees and local developer environments.
What is Codex Git Worktree
The core value of Codex Git Worktree is binding dialogue isolation and code isolation together. Built upon native git worktree, the main working tree and linked worktrees maintain separate files, HEAD pointers and index states, while sharing repository objects and branch references.
This architecture unlocks practical parallel workflows. One Codex task can patch production bugs, while another task refactors modules or runs test suites. Uncommitted changes from one task remain invisible in other worktrees. This characteristic makes worktrees ideal for long-running tasks, experimental modifications, and teams that frequently switch project contexts.
According to OpenAI official documentation (2026), Codex stores managed worktrees under the path $CODEX_HOME/worktrees. Each worktree starts from the selected HEAD commit at task initialization.
Worktrees do not default to normal branch checkouts; they run under detached HEAD mode. This is the key mechanism that allows Codex to spin up multiple independent task environments simultaneously.
Distinction between Local Checkout, Worktree and Handoff
Codex Local checkout and Worktree are not two separate Git installations. They represent two working locations within the same Git repository.
| Mode | File Location | Suitable Scenarios | Key Notes |
|---|---|---|---|
| Local | Regular project directory opened on your machine | Work requiring IDE access, active local service execution | Directly modifies your current local checkout |
| Worktree | Independent directory created and managed by Codex | Parallel backend tasks, isolated experiments | Runs on detached HEAD by default |
| Handoff | Data transfer channel between the two environments | Execute tasks in backend, then inspect locally | Codex automates Git migration steps |
OpenAI documentation frames Local as the frontend workspace and Worktree as the backend workspace. Developers can run validation and automated checks entirely inside a worktree. When a task needs manual human review, local service startup or manual IDE editing, use Handoff to transfer code and conversation context back to Local. When sending the task back to Worktree, Codex resumes the linked worktree associated with that conversation session.
How to Launch a Codex Worktree Task
Starting a Codex worktree task follows four standard steps:
- Select the Worktree environment when creating a new chat session.
- Choose a starting reference branch, which may be
main, a feature branch, or your current branch containing uncommitted edits. - Submit your task prompt; Codex will create the worktree and complete the initial checkout.
- Continue work inside the Worktree, or trigger Handoff to shift the task to your Local environment as needed.
If a project requires dependency installation, build pipelines or preloaded test datasets, teams can define a setup script inside the .codex local environment folder.
Sample setup script:
This setup script runs automatically when Codex creates a new worktree. It reduces environment drift, eliminating the common issue of code that “works locally but fails inside worktrees”. Developers can also wrap service launch and test execution commands within the local configuration to make environment preparation repeatable.
Manual Git Worktree Command Reference
Even without the Codex graphical interface, native Git commands can manage persistent worktrees. The workflow below creates an independent branch and directory named fix/login-timeout derived from the main branch.
Use these commands for routine inspection and cleanup:
git worktree list: Display all worktree paths, commit SHAs and associated branchesgit worktree remove: Safely delete a worktree with clean working stategit worktree prune: Clean stale metadata after a directory has been manually deleted
Git official documentation warns that untracked or uncommitted files will block standard remove operations. Only run git worktree remove --force after confirming you no longer need the local files in that worktree.
Branch Strategies for Parallel Tasks
Git enforces a core protection rule: one Git branch cannot be checked out in two separate worktrees at the same time. This prevents race conditions from concurrent writes to a single branch reference.
The typical error message returned by OpenAI Codex is:
A stable recommended pattern follows the principle: one task, one branch.
- Read-only analysis or quick experiments: Use Codex default detached HEAD mode.
- Tasks requiring persistent changes: Create a dedicated unique branch within the worktree, for example
codex/fix-cache. - Prepare for local handoff: Prefer Handoff workflow; avoid re-checking the same branch manually in Local.
- After merge completion: Delete the worktree and run
git worktree pruneto clear stale metadata.
Multiple tasks starting from the same main commit can run in parallel and modify distinct files. Final integration still requires standard testing, code review and pull request workflows to resolve merge conflicts.
How Ignored Files Enter Codex Worktrees
Worktrees created by Codex are checked out from Git, so .gitignore excluded local files will not be automatically copied into new worktree directories.
When local development configuration must be shared across worktrees, create a .worktreeinclude file at the repository root.
OpenAI documentation clarifies that Codex only copies files matching paths listed inside .worktreeinclude. It will not overwrite existing files in the worktree, nor will it follow symbolic links to source files.
Sensitive credentials still require strict team secret management. .worktreeinclude is not an access control mechanism. If tasks need to connect external tool capabilities into the Agent runtime, relevant MCP configurations can be included in the project environment preparation pipeline. You can reference the documentation of 4sapi MCP service as a standard capability orchestration example, but access secrets must never be committed to the repository.
Worktree Cleanup and Recovery
Each worktree occupies separate local directories, build cache and generated artifacts. Disk management must be part of the team workflow.
OpenAI official documentation states Codex retains up to 15 Codex-managed worktrees by default. The system prioritizes preserving active tasks, pinned conversations and permanent worktrees. When linked conversations are archived or worktree count exceeds the configured limit, Codex may automatically delete managed worktree directories. A snapshot will be saved before deletion, and users may restore the environment when reopening the conversation.
For long-lived environments that must survive conversation archiving, create a permanent worktree. Permanent worktrees will not be automatically purged when chats are archived.
Frequently Asked Questions
Q: What is the difference between Codex Worktree and regular `git clone`?
Worktrees share Git objects and metadata with the main repository, so creation overhead is much lower than cloning a full repository. Each worktree still maintains independent files, HEAD pointer and index. This pattern is optimized for parallel branch work within a single repository.
Q: Why can I not checkout a worktree branch locally?
Git prevents one branch from being checked out in multiple worktrees simultaneously. Use Handoff to move conversation and code changes to Local, or switch to a different branch inside the worktree before local checkout.
Q: When should detached HEAD mode be used?
Detached HEAD works well for read-only analysis, temporary experiments and tasks that do not require direct push operations. When you need commits, pushes or pull requests, create a named branch within the worktree to preserve your changes.
Q: Can `.worktreeinclude` copy all local files?
No. It only copies files with paths explicitly listed in this file. Codex skips symbolic links and will not overwrite files already present in the target worktree.
Q: Are chat records retained after a worktree is deleted?
Conversation history persists in chat logs. For Codex-managed worktrees, Codex creates a snapshot before deletion, offering restore options when reopening the chat. Permanent worktrees are not automatically removed on conversation archive.
Conclusion
Codex Git Worktree is designed to split multiple concurrent development jobs into isolated execution units. Developers can run lightweight experiments with detached HEAD, create dedicated branches for work that needs version tracking, and use Handoff to transfer context between backend worktrees and local environments.
Native Git defines the underlying shared object model and branch locking constraints, while OpenAI documentation supplements rules for directory management, environment scripting and recovery behavior. This document synthesizes OpenAI and official Git git worktree materials as of September 10, 2026. Codex UI and default settings are subject to version updates; verify details against live official documentation before production usage.
International access: https://4sapi.com
Domestic access: https://4sapi.cn
