A Codex task running in the same Git checkout as your own edits can collide with unfinished work. Worktree mode gives the task a separate checkout, keeping its changes apart from the original project files.
Codex in the ChatGPT desktop app manages the worktree and its chat together. Worktrees share the repository's commits and branches but have their own working files; a detached HEAD is normal before a branch is created for the worktree.
The intended starting revision should already be selected in a trusted Git project added to the app. A task that builds or tests the project also needs its dependencies in the worktree; tools installed only in the original directory may need a local environment setup script.
Steps to start a Codex task in a worktree:
- Open the Git project in the ChatGPT desktop app.
- Start a New chat for the project.
- Enter /worktree in the composer.
- Select Worktree when its description is Turn worktree mode on.
With worktree mode active, a subsequent command lookup offers Turn worktree mode off. Selecting that option would cancel worktree mode.
- Enter the task you want Codex to perform in the worktree.
Project code and task commands can run with the app's active permissions. Worktree selection separates checkout files; permission settings govern file and network access.
- Submit the prompt.
Worktree created confirms that the app prepared the separate checkout.
- Open the chat's terminal with Ctrl+`.
The shortcut uses the Control key on macOS as well.
- Verify the chat's selected checkout with pwd in its terminal.
$ pwd /home/user/.codex/worktrees/1b77/worktree-demo-reader
The printed path should be the separate worktree directory used by this chat. The app manages the worktree directory name, so its path varies between tasks.