Codex worktrees explained with a real project workflow

A Git worktree gives a task another working directory while sharing repository history. In Codex, this lets a conversation work on an isolated checkout so changes do not immediately mix with edits in your main working copy. It is useful for parallel features, background tasks, and experiments that may be discarded.

Isolation does not remove the need to understand the starting state. Confirm the branch or working tree used to create the task, and decide whether uncommitted local changes must be included before beginning.

A new worktree contains tracked files but may not contain dependencies, generated artifacts, or ignored local configuration. Configure a setup script for repeatable installation and build steps. Keep secrets out of repositories and copy ignored files only through a deliberate project mechanism when the client supports it.

Run a small readiness check: dependency installation, configuration presence, application start, and the narrowest relevant test. Record what is intentionally unavailable.

Give the worktree a clear branch of work: one issue, one feature, or one review. Avoid assigning multiple tasks that would be difficult to evaluate or merge independently. Let the task inspect repository instructions and preserve unrelated work.

Use the integrated diff or Git tools to examine the actual changes. A clean isolated directory makes the diff easier to read, but it does not make every change correct.

You can keep working in the isolated checkout, create or push a branch, open a pull request, or hand the conversation back to the local project when supported. Choose based on how your team reviews and tests changes.

Be aware that a branch checked out in one worktree cannot simultaneously be checked out in another. If you need to use the same branch in your main checkout, move or detach the existing worktree relationship through the supported workflow.

For an AboutCodex template change, create the worktree from the intended repository state, run the setup action, edit the theme or companion plugin, and test representative archives and articles. Review the diff, keep content migration separate from theme code, and move the finished task only after the local site checks are recorded.

Confirm the starting revision, setup result, changed files, targeted checks, responsive routes when relevant, and the final branch or handoff state. State whether the change was deployed; a completed worktree is still a local or remote working copy until the release workflow says otherwise.

• Official worktree documentation
• Local environment setup
• Use the regression-plan skill

A worktree is most useful when a task needs isolation from the current checkout: parallel feature work, a clean comparison branch, or a change that should not disturb an active local environment. It is less useful when the application depends on machine state that only exists in the main checkout and cannot be reproduced safely. In that case, document the dependency before choosing the environment.

Keep one coherent objective per worktree and avoid sharing generated state, ports, or mutable services without a plan. Name the starting branch, record uncommitted input when it matters, and decide how the completed change returns to the main workflow. Isolation helps only when the handoff is clear.

• OpenAI worktree documentation
• Plan a regression check

A server can start successfully in the main checkout and fail in a worktree because an environment file, uploaded asset, dependency directory, or database path is not present. Ports may collide when two copies run at once. Build tools can also cache absolute paths from the first checkout. Run a narrow startup check before beginning a long implementation.

When the task finishes, inspect the diff, run project-required checks inside the worktree, and confirm that ignored files do not contain the only copy of the result. Keep the branch or patch until the destination checkout contains the reviewed change.

OpenAI worktree documentation. Source checked September 10, 2026.