How to start a Codex task in a worktree

A Codex task that runs in Local can collide with uncommitted edits, a foreground development server, or a branch you still need in your regular checkout. Starting the thread in Worktree gives Codex App a separate Git checkout for the task while the original project directory stays available for your own work.

Codex App creates Codex-managed worktrees under $CODEX_HOME/worktrees from the starting branch selected in the new-thread composer. The worktree normally starts from the selected branch's HEAD commit in detached-HEAD state, so the task can make file changes without checking out a new branch in the local project.

Use Worktree mode only for projects inside a Git repository. When the task is ready for foreground review, use Create branch here to keep working from the worktree, or use Hand off to move the thread and code into Local without manually checking out the same branch in two places.

1. Record the local checkout state before starting the background task.

   $ git -C /home/user/src/example-app status --short --branch
   ## main

   If the local checkout already has intentional edits, save this output so the later check can confirm Codex did not add unrelated files there.

2. Open the Git-backed project in Codex App.

   Worktree mode requires a Git repository. Non-version-controlled projects run in the project directory instead.

3. Start a new thread and select Worktree under the composer.
4. Choose the starting branch below the composer.

   Codex creates the worktree from the selected branch's HEAD commit. If the selected branch has local uncommitted changes, those changes are applied to the worktree too.

5. Select a local environment only when the worktree needs setup scripts before the task starts.

   Use the same dependency setup that the task needs to run tests or build commands inside the worktree.

6. Submit the task prompt.

   Update the login form tests in a worktree. Run the existing test command and report the final git status.

7. Confirm that the new thread is attached to a worktree.

   $ git worktree list
   /home/user/src/example-app                   f67996c [main]
   /home/user/.codex/worktrees/example-app-task f67996c (detached HEAD)

   The exact worktree name is managed by Codex, but the second row should point under $CODEX_HOME/worktrees and show detached-HEAD state unless a branch was created there.

8. Check the task's worktree status from the thread terminal after Codex starts editing.

   $ git status --short --branch
   ## HEAD (no branch)
    M tests/login-form.test.js

   Detached HEAD is expected for a Codex-managed worktree before Create branch here is used.

9. Recheck the original local checkout from a separate terminal.

   $ git -C /home/user/src/example-app status --short --branch
   ## main

   The output should match the starting state recorded before the thread was launched.

10. Choose where to continue once the task is ready for review.

    Use Create branch here when the work should stay in the worktree. Use Hand off → Local when the existing checkout should receive the thread and code. Files ignored by Git do not move during handoff.