Isolated Codex tasks with Git worktrees

A Codex worktree task runs one session in its own Git worktree, so its edits, installs and tests never touch your main checkout. Codex CLI 0.157.1 creates a managed worktree with --worktree or /worktree; git worktree add lets you name the path and branch. It is finished only when its gates pass and its commits sit on a branch.

You asked Codex to fix a flaky auth test while you kept working on a migration in the same directory. Twenty minutes later your working tree holds both sets of changes, npm install has rewritten the lockfile under you, and you cannot tell which edits are yours. This page is for the developer who runs Codex locally and wants every task in its own checkout, with a clean way to verify it, keep it and throw it away.

What you get from running Codex tasks in worktrees

• A decision table for managed worktrees (codex --worktree), explicit ones (git worktree add) and the desktop app.
• The facts about what a managed worktree does and does not carry over, measured on Codex CLI 0.157.1.
• A bootstrap script that makes a fresh worktree runnable without copying production secrets.
• Two copy-paste prompts: one that starts a task safely inside a worktree, one that hands it back ready to merge.
• A gate you run before you read any diff, and a cleanup order that never deletes an unmerged commit.

Coordinating many worktrees at once (lanes, fan-out scripts, merge order) is the job of Codex multi-agent workflows. This page covers one task’s worktree from creation to removal.

Which kind of Codex worktree should you use?

Worktree support is on by default since Codex CLI 0.156.0 (the worktrees feature is stable and true in codex features list, 0.157.1). A session still runs in your current directory unless you opt in. Codex 0.162.0 (2026-10-08) added managed Git worktree tools that create and list worktrees from trusted projects (OpenAI’s release notes). The carry-over measurements in the next section were taken on 0.157.1, and the release notes do not say whether the carry-over changed, so repeat that check after you upgrade.

You want	Use	Where the checkout lives	Branch
A quick isolated interactive task	codex --worktree	$CODEX_HOME/worktrees/<id>/<repo> (by default under ~/.codex/)	None: detached HEAD at your current commit
To move a running conversation into isolation	/worktree inside the session (“start or continue a conversation in a new worktree”)	Same managed location	None until you create one
A scripted, non-interactive task	codex exec --worktree, or git worktree add plus codex exec -C DIR	Managed location, or a path you choose	None with codex exec --worktree (detached HEAD); named with git worktree add -b
A path, branch and base you control (ports, CI scripts, review tooling)	git worktree add -b BRANCH PATH BASE, then codex in that path	Where you put it	Named from the start
Threads in the desktop app	The app’s worktree option per thread (codex app, macOS and Windows)	Managed by the app	See Codex desktop app mastery

codex fork --worktree and codex resume --worktree exist too (checked in --help, 0.157.1): they continue an earlier session in a new managed worktree, which is the clean way to try a second approach without disturbing the first.

The rule of thumb: use --worktree for throwaway or exploratory tasks, and git worktree add when the result must become a named branch and pull request, or when a script, a port allocator or a teammate needs to find the checkout by path.

What does a managed Codex worktree carry over?

We ran codex exec --worktree on Codex CLI 0.157.1 (2026-09-26) in a repository with a modified tracked file, an untracked file and a gitignored .env. The managed worktree contained:

State in your main checkout	In the managed worktree?
Committed files at HEAD	Yes, checked out at the same commit
The current branch	No. The worktree is on a detached HEAD
Uncommitted edits to tracked files	No. The file has its committed content
Untracked files	No
Gitignored files (.env, node_modules/, build caches)	No

Three consequences follow. Commit (or stash and re-apply) anything the task depends on before you start it. Expect every managed worktree to need a dependency install and local configuration. Create a branch before the agent commits, because commits on a detached HEAD belong to no branch and are easy to lose when the worktree is removed.

The managed worktree also outlives the session: in the same run it was still listed by git worktree list after codex exec exited. codex --help in 0.157.1 lists no subcommand that removes a worktree, so removal is Git’s job, from any checkout of the repository.

Run one Codex task in an isolated worktree

1. Check what the task will start from.

   git status --short        # anything listed here will NOT reach a new worktree
   git branch --show-current
   git worktree list         # existing worktrees, including Codex-managed ones

   Commit the work the task needs. If you do not want to commit half-finished code, create the worktree from the last good commit and describe the missing piece in the prompt instead.

2. Create the worktree. Pick one of the two forms.

   Managed, for a quick task:

   codex --worktree

   The session opens in $CODEX_HOME/worktrees/<id>/<repo>; in a second terminal, find it with git worktree list and run the bootstrap there before you send the first prompt.

   Explicit, when you want the branch and path fixed up front:

   git fetch origin
   git worktree add -b codex/fix-auth-flake ../myapp-fix-auth-flake origin/main
   cd ../myapp-fix-auth-flake
   codex

   Replace origin/main with your repository’s real default branch (git symbolic-ref refs/remotes/origin/HEAD prints it). Git refuses a branch that is already checked out in another worktree, which is a feature: two agents cannot share one branch by accident.

3. Bootstrap the checkout. Run this from inside the new worktree, in your own terminal rather than through the agent, so installs get the network access the sandbox withholds:

   #!/usr/bin/env bash
   # bootstrap-worktree.sh: make a fresh worktree runnable
   set -euo pipefail
   MAIN=$(git worktree list --porcelain | awk 'NR==1 {print $2}')   # the main checkout is always listed first
   for f in .env.development .env.test; do                          # development files only, never production
     if [ -f "$MAIN/$f" ]; then cp "$MAIN/$f" .; fi
   done
   npm ci                                                           # install from the lockfile, do not re-resolve
   grep -qs '^PORT=' .env.development || echo "PORT=$((4000 + RANDOM % 1000))" >> .env.development   # a port no other worktree is likely using; added once

   Re-running the script is safe: it copies the same files again, reinstalls from the lockfile and keeps the port it already assigned. Keep an allowlist of files to copy, as above. Copying every gitignored file is how a production key ends up in a directory an agent can read. If your repository already has a setup script, call it here instead. When the task also needs its own database or service stubs, give it a full per-task stack as in ephemeral environments for agent tasks.

4. Start the task with a scoped prompt. Paste the first prompt below. It tells Codex where it is, what it may touch and what “done” means.

5. Prove the result before you read it. Run the gate in How do you verify a worktree task without reading every line? below. Read the diff only when the gate passes, and then only the files it flags.

6. Integrate through the normal path. Push the branch and open a pull request, so CI and your review rules apply exactly as they do to human work. Do not copy files between worktrees by hand, and do not git apply several agent patches onto one branch without rerunning the gates after each.

7. Remove the worktree only after the work is safe. See clean up Codex worktrees without losing commits.

Copy-paste prompt: start a task inside a worktree

You are working in a dedicated Git worktree. Work only inside this directory.

First:
1. Run `git rev-parse --show-toplevel`, `git status --short` and `git branch --show-current`, and tell me what you found.
2. If HEAD is detached, create a branch with `git switch -c codex/fix-auth-flake` before changing anything.
3. Read AGENTS.md for the build, lint and test commands.

Task: make tests/auth/session-refresh.test.ts pass reliably. It fails about one run in five on CI. Find the cause (timer, shared state or ordering) before changing code; do not add retries or increase timeouts to hide it.

Rules:
- Do not touch files outside src/auth/ and tests/auth/ unless you stop and ask first.
- Do not install new dependencies, change the lockfile, or read or write any .env file.
- Do not push, merge, deploy, or remove this worktree.

Done means: the test passes 20 times in a row with `for i in $(seq 20); do npx vitest run tests/auth/session-refresh.test.ts || exit 1; done`, and type check, lint and the full test suite pass. End with each command you ran, its exit code, the root cause in two sentences, and the list of files you changed.

Adjust the test file, paths and repeat command to your project; the structure (locate, branch, rules, a done condition with exit codes) is what makes the prompt work in any worktree.

How do you verify a worktree task without reading every line?

A worktree gives you something the shared checkout never does: a diff that belongs to exactly one task. Use it. Run these checks from the task’s worktree, in order, and stop at the first failure.

#!/usr/bin/env bash
# worktree-gate.sh BASE ALLOWED_PATHS_REGEX
# example: ./worktree-gate.sh origin/main '^(src/auth/|tests/auth/)'
set -euo pipefail
base="$1"; allowed="$2"

test -z "$(git status --porcelain)" || { echo "FAIL: uncommitted changes"; exit 1; }
git symbolic-ref -q HEAD >/dev/null   || { echo "FAIL: detached HEAD, create a branch"; exit 1; }

stray=$(git diff --name-only "$base"...HEAD | grep -v -E "$allowed" || true)
[ -z "$stray" ] || { echo "FAIL: files outside the task:"; echo "$stray"; exit 1; }

npm run typecheck                    # separate lines: set -e stops on the first failing check
npm run lint
npm test

codex review --base "$base" || echo "WARN: codex review did not complete"   # advisory: findings never fail the script
echo PASS

codex review --base runs the built-in review prompt. In Codex CLI 0.157.1 it cannot take custom instructions as well: codex review --base main "..." fails with the argument '--base <BRANCH>' cannot be used with '[PROMPT]' (checked 2026-09-26), and --uncommitted has the same restriction. Put standing review rules, such as “flag behaviour without a test”, in AGENTS.md instead of on the command line. codex review is advisory in this script: it prints findings, and codex review --help in 0.157.1 documents no exit code that fails on them, so a PASS line means the mechanical checks passed. If the review cannot run at all (not signed in, no network), the || echo prints a warning instead of letting set -e stop the script. Read its output, and treat the files it flags as the ones you read by hand.

Check	What it catches
Clean status and a named branch	Work that exists only in the worktree and would vanish on removal
Allowed-paths diff	An agent that “fixed” something outside its task
Type check, lint, tests	Broken behaviour, run in isolation from other tasks’ edits
codex review --base	Logic errors and missing tests, from a second pass that did not write the code
CI on the pull request	Everything above again, on a clean machine, plus integration with the latest base

You sign off on two things: the done condition in the prompt before the task starts, and the files the gate flags afterwards. Auth, payments and migrations always get a human read, whatever the gate says. The done condition works best as an executable acceptance criterion (how to turn acceptance criteria into failing tests), and the pull request should carry the evidence bundle an agent’s pull request must prove. For how review scales across a team, see Codex review strategies.

Copy-paste prompt: hand the worktree back ready to merge

Prepare this worktree for review. Do not push, merge or delete anything.

1. Run `git status --short`. Commit every change that belongs to the task with a message that says what changed and why; list anything you did not commit and why.
2. Confirm HEAD is on a named branch, not detached.
3. Run `git diff --name-only origin/main...HEAD` and flag every file outside src/auth/ and tests/auth/.
4. Run type check, lint and the full test suite, and report each command with its exit code.
5. Write a pull request description: the problem, the root cause, the fix, how it was tested, and the risks a reviewer should check by hand.

Clean up Codex worktrees without losing commits

Every task leaves a checkout, and a managed one sits under $CODEX_HOME/worktrees/ where you will not notice it filling the disk. Clean up in this order:

git worktree list                                  # find the path, including managed ones
git -C PATH status --short                         # must be empty
git -C PATH log --oneline BASE..HEAD               # commits not yet on the base
git branch -r --contains "$(git -C PATH rev-parse HEAD)"   # empty output = not pushed anywhere
git worktree remove PATH
git worktree prune                                 # drop records of worktrees deleted by other means

PATH is the worktree’s directory from git worktree list, and BASE is the branch the task started from, such as origin/main. git worktree remove refuses a worktree with modified or untracked files. Add --force only after the status and log checks show there is nothing you want, because it deletes those files for good. Delete the branch last, with git branch -d (which refuses unmerged branches), not -D.

When Codex worktree tasks go wrong

Symptom	Cause	Recovery
The agent reports missing modules or config on its first command	Managed and new worktrees get no gitignored files	Run the bootstrap script, then restart the task
The task ignores a fix you made minutes ago	The worktree starts from the last commit, not your working tree	Commit the fix, then codex fork --worktree or start again
Commits disappeared after cleanup	The agent committed on a detached HEAD; git worktree remove does not refuse that, and it deletes the worktree’s own reflog	Before Git garbage-collects them, list orphaned commits with git fsck --lost-found, find yours with git show SHA, then git branch rescue/TASK SHA. Prevent it with the branch step in the first prompt and the gate’s named-branch check
Git reports the branch is already used by (or checked out in) another worktree	The branch is checked out in another worktree	Use a new branch name, or remove the other worktree first
The agent cannot commit, or asks for approval on every git write	A worktree’s Git metadata lives in the main repository’s .git/, which can sit outside the sandbox’s writable area	Commit from your own terminal, or make that directory writable deliberately with --add-dir (see permissions and sandboxing)
Codex says “The new worktree is not trusted; run Codex there.”	The new checkout path has not been marked as trusted, and untrusted projects do not supply AGENTS.md (since Codex CLI 0.150.0)	Run codex in the worktree, accept the trust prompt only for a repository you trust, then restart the task so it reads AGENTS.md
Two dev servers fight over one port	Every worktree inherited the same PORT	Give each worktree its own port in the bootstrap step and pass it to the dev server and end-to-end tests
Two tasks’ changes conflict at merge	Both touched a shared file (router, barrel export, schema)	Merge one, rebase the other on it, rerun the full gate. Next time, split tasks by file ownership as in multi-agent workflows
The disk fills up	Every worktree holds its own dependencies and build output, and managed worktrees stay after the session ends	Remove finished worktrees weekly with the cleanup sequence above

Isolation stops at the filesystem

A worktree separates files, not the outside world. Tasks in different worktrees still share your production database, cloud accounts, third-party APIs and any secrets in your shell environment. Keep those out of the bootstrap step, and tell the agent in the prompt which remote systems it must not touch. A per-task database and service stubs close most of that gap; the ephemeral-environments page linked in step 3 shows how.

Where to go next with Codex worktrees

• Before this page: configure Codex and write AGENTS.md for Codex, so every worktree knows its build and test commands.
• Next: Codex multi-agent workflows to run several worktree tasks as parallel lanes, and non-interactive Codex with codex exec to script them.
• For tasks too heavy for a laptop: Codex cloud environments.
• The same isolation in Claude Code and Cursor: running parallel agents in isolated worktrees, and tools that manage many at once in parallel agent tools.