How to Use Codex CLI Worktrees

The shortest working setup

You need Codex CLI 0.154.0, a local Git repository, and the experimental worktrees feature enabled. Check the version before looking for a flag that an older binary does not know.

codex --version
npm install -g @openai/codex@0.154.0
codex features enable worktrees
codex features list

The persistent command writes the feature choice to your Codex configuration. If you would rather test it once, leave the configuration alone and add --enable worktrees to that invocation.

Now start a fresh isolated session, a headless task, or a fork of a conversation you already have:

codex --enable worktrees --worktree "Upgrade the test runner and run its suite"
codex exec --enable worktrees --worktree "Find the flaky test and propose the smallest fix"
codex fork --enable worktrees --worktree <session-id> "Try the lower-risk implementation"

For the interactive fork, <session-id> is the chat ID shown by /status. Version 0.154.0 requires an explicit ID here. codex fork --worktree --last is not accepted.

The same workflow is available inside the terminal interface. Type /worktree, then choose whether to continue the current conversation in a new checkout, start a fresh conversation there, or browse worktrees that Codex already manages for this repository.

What Codex creates

A managed worktree is a second checkout attached to the same Git repository. Think of the repository as a library catalogue shared by two reading rooms. Each room can lay out a different set of pages, but both refer to the same commits and branches.

Codex creates the new checkout at the source repository's committed HEAD, in detached HEAD state, then binds that checkout to the new session. Detached HEAD means the checkout points straight at a commit instead of moving a named branch. Your source checkout stays where it was.

That clean starting point has one sharp consequence: uncommitted edits in your original checkout do not follow the session. Neither do ignored files such as a typical .env or node_modules directory. OpenAI documents .worktreeinclude copying for Desktop-managed local worktrees, but explicitly scopes that behavior away from command-line-created worktrees. For the CLI path, plan to bootstrap what the task needs.

If you launch Codex from a directory nested inside the repository, the managed checkout preserves that relative location. Starting from apps/web, for example, places the session in the matching apps/web directory inside the new worktree, provided that directory exists in the committed revision.

The practical workflow, from launch to keep

The safest routine has five parts: start clean, confirm where you landed, do the work, inspect the evidence, then deliberately keep or discard it.

1. Start from the commit you actually want

--worktree is a boolean switch, not a branch or base selector. It starts from the HEAD of the repository you point it at. Check out the intended base branch and commit any source changes that the task needs before launching. You can use -C <repo-path> to point Codex at a specific local checkout.

Use a fresh session when the task stands alone. Use a fork when the new attempt needs the original conversation's decisions and constraints. A fork preserves the transcript in a new chat while moving the new work into an isolated checkout, so the first attempt remains intact for comparison.

2. Confirm the checkout before editing

Ask Codex to run pwd, git status --short, and git rev-parse --short HEAD at the start. The working directory should be the managed path, the status should be clean, and the commit should match the source HEAD you intended to use.

This check catches the most expensive boring mistake: doing excellent work against the wrong base.

3. Install only what this lane needs

A worktree isolates checked-out files. It does not create a container, reserve a port, clone a database, or install dependencies. Run the repository's normal setup command in the managed checkout. Give concurrent sessions separate ports, temporary databases, cache directories, and test accounts when those resources can collide.

This is the main limit to understand. Two clean Git diffs can still interfere if both sessions migrate the same development database or bind the same port.

4. Inspect the diff and resume the right thread

Inside the worktree session, /review can inspect uncommitted changes. From another terminal, first use /worktree, choose Browse worktrees, select the checkout, and choose Copy working directory. Then run git -C "<worktree-path>" status --short, git -C "<worktree-path>" diff --stat, and git -C "<worktree-path>" diff.

Do not run codex review --worktree. Version 0.154.0 rejects that flag combination. Review the active worktree from inside its session or point normal review tooling at its copied path.

To continue later, type /worktree, choose Browse worktrees, select the managed checkout, then choose Resume owner thread. Do not add --worktree to codex resume; resuming should return to the checkout already bound to the session, not allocate another one.

5. Keep the change before cleaning the checkout

For a change you want, run the relevant tests, commit it in the worktree, and copy the commit SHA. In the original checkout, use git cherry-pick <sha> to bring that commit onto your current branch. Cherry-pick before removing the worktree so the detached commit has a durable destination.

If the work deserves its own review branch, run git switch -c codex/<task> in the worktree, commit, push, and open a pull request. Git will not let the same branch be checked out in the original checkout at the same time. Push it from the worktree, or remove that worktree before checking the branch out elsewhere.

CLI-created worktrees are not automatically cleaned up. Once the change is safely committed or intentionally discarded, confirm the checkout is clean and run git worktree remove <worktree-path> from the source repository. Avoid --force. git worktree prune can clear stale Git registrations later, but it is not a substitute for checking whether a session still owns the checkout.

What this changes in the budget

The native feature removes a small but repeated layer of shell glue. Before 0.154.0, a CLI user had to create a path, create or detach a branch, launch Codex in that directory, remember which chat belonged to it, and later clean both Git and session state. The new flag creates and binds the checkout in one launch, while /worktree gives you a repository-aware browser and resume route.

For an existing Codex subscriber, the checkout carries no separately published fee. Codex Plus is $20 a month. A commercial agent workspace that organizes parallel worktrees, Unstoppable, starts its paid Pro plan at $19 a month, with Business at $29 per user and Enterprise at $49 per user. Native Codex can now cover the narrow checkout-and-resume job inside the subscription you already use.

It does not replace the rest of that paid workspace category. Cross-agent dashboards, port allocation, shared environment setup, test aggregation, pull request tracking, team policy, and cost reporting still sit above the raw checkout. Parallel sessions also draw from the same Codex usage allowance. The right financial read is not "free parallel development." It is "one less orchestration tool if isolation was the only reason you bought it."

For a broader view of the product around this feature, the Codex review covers the local CLI and agent workflow. The earlier Codex CLI 0.152.0 explainer shows why release-specific limits matter when you automate the terminal.

Seven worktree jobs, ranked by payoff

1. Risky dependency upgrades

A maintainer can launch a worktree for a framework, package-manager, or test-runner upgrade, let Codex edit lockfiles and configuration, and run the full suite without dirtying the feature work open in the main checkout. The payoff is a reviewable upgrade lane that can be discarded without a stash or a rollback of unrelated edits.

2. Competing implementations of one feature

A tech lead can fork the same planning conversation into two managed worktrees, ask one session for the smallest patch and the other for a more structural approach, then compare diff size, tests, and migration risk. The payoff is an evidence-based choice without letting the second attempt overwrite the first.

3. Bug triage beside active product work

A product engineer halfway through a feature can start a clean worktree from committed HEAD to reproduce a production bug. Codex can instrument, test, and fix the bug in that lane while the unfinished feature remains untouched. The payoff is fewer emergency stashes and a cleaner hotfix diff.

4. Large codemods and refactors

A platform team can give a wide rename or API migration its own checkout, run formatters and tests there, and inspect the resulting file set before it enters the main branch. The payoff is containment: generated churn stays separate until it earns a commit.

5. A review-fix lane

A pull request author can commit the review base, launch an isolated Codex session from that state, and address review comments without disrupting another branch checked out locally. The payoff is a focused correction series that can be pushed from the worktree when ready.

6. Reproducible maintenance runs

A build engineer can use codex exec --worktree for a focused task such as updating generated files or investigating a flaky test. The headless run gets a clean tracked-file checkout and a persisted session that can be inspected later. The payoff is less accidental contamination from whatever happens to be open in the primary working tree. The catch is that the automation must own dependency setup and cleanup.

7. Safe repository orientation

A new team member can let Codex map an unfamiliar codebase and try a small documentation or test change in a managed worktree before touching the usual checkout. The payoff is psychological as much as technical: exploration has a visible boundary and an easy discard path.

Three products worth building around the gap

1. The strongest bet: a worktree readiness layer

Build a small local tool that turns a fresh managed checkout into a runnable, collision-free task lane. It would detect the project stack, run the approved dependency setup, allocate a port, create a temporary database or schema, expose only selected secrets, perform a health check, and print the matching cleanup plan.

The demand is broad: git worktree gets about 9,900 US Google searches a month, and what is a git worktree gets another 590. The native Codex feature solves checkout creation but leaves runtime readiness open, which makes this the strongest opportunity.

The smallest sellable version needs a repository manifest, setup and teardown commands, port reservation, environment-file templating, and a status check. The honest catch is security. A tool that copies secrets or points two agents at one database can create more risk than it removes. OpenAI could also add first-party lifecycle hooks that narrow the gap.

2. A cross-agent lane dashboard

Build a desktop or terminal dashboard that discovers worktrees across repositories and tools, then shows owner session, branch or detached state, changed files, test result, Codex usage, pull request, disk footprint, and a safe resume or cleanup action.

git worktree claude code gets about 480 US searches a month, and the exact phrase parallel coding agents gets 10. That latter query is small, but paid behavior is visible: Unstoppable starts at $19 a month for a product that includes parallel agent worktrees. The buyer is a developer already juggling Codex, Claude Code, and ordinary terminals.

An MVP can stay read-only: enumerate Git worktrees, match known session metadata, run status and test commands on demand, and deep-link back to each agent. The catch is native competition. Codex 0.154.0 already browses its own managed worktrees, so this product must win on cross-agent visibility, runtime state, and team reporting.

3. An integration and cleanup gate

Build a guard that sits between a finished agent lane and the main branch. It would verify a clean status, run the required test set, detect files changed by other active worktrees, recommend a cherry-pick order, and refuse destructive cleanup while commits remain unintegrated.

The questions are already visible in search demand: git remove worktree gets about 390 US searches a month, git worktree vs branch gets 320, and git worktree prune gets 140. Those queries cluster around the moment when isolated work has to become shared work.

The MVP is a local Git command plus a small policy file. It can be useful without editing a single line automatically. The catch is distribution: Git clients and CI vendors can add the same checks, so a standalone tool needs excellent support for multiple coding agents and messy real repositories.

Limits that should change your decision

Use native worktrees when file isolation is the problem. Do not mistake them for full environment isolation.

There is also no CLI equivalent of the Desktop app's Handoff button in this release. Bringing code back is still a Git decision: commit and cherry-pick, push a branch, or discard and remove. That explicit step is healthy. Isolation is useful precisely because nothing should flow into the main checkout by accident.

Your Monday move: pick one non-critical dependency update, run it with codex --enable worktrees --worktree, compare the diff and tests from the copied checkout path, cherry-pick only the accepted commit, then remove the worktree. If you want a reliable isolated-agent workflow built around your repositories, I can help you design the production system.