# Codex worktree: a separate working copy for a second task > Working copy of Codex CLI 0.155.1: experimental worktree flag, source HEAD, checking the new folder, preserving the result, and safe removal. Source: https://ailoot.ai/blog/en/codex-worktree-separate-task/ Canonical: https://ailoot.ai/blog/en/codex-worktree-separate-task/ Language: en Publisher: Ailoot (https://ailoot.ai/) Translation: guide-086 Revision: sha256-e22c51271830a65b49daa69bde581fbf22605fc80bb6657964ae0e210e37c280
Key takeaway In Codex CLI version 0.155.1, you create a separate working copy for a second task with `codex --enable worktrees --worktree`. The feature is experimental and disabled by default: unless you have already enabled it, Codex will refuse to start with `--worktree` without `--enable worktrees`. The copy is created from the original project's latest commit (HEAD), without uncommitted changes, in a detached HEAD state—with no named branch attached.
For example, you are using Codex CLI to refactor one module when a second task comes up: writing tests for another module. Opening a second session in the same folder is risky: it is easy to mix up changes from the first and second tasks. The `--worktree` flag creates a separate folder of the same project for the second task, leaving the first one untouched. Practical resources on working with agents in parallel: [Ailoot documentation](https://ailoot.ai/docs/). ## What does the Codex --worktree flag create? In Git terminology, a worktree is an additional working folder linked to the same repository: it shares the commit history but has its own set of files on disk. In Codex CLI 0.155.1, the `--worktree` flag uses this Git mechanism to start a new agent session in a separate folder, leaving the folder where the first task is already running untouched. The new working copy contains the files from the commit that the original project's HEAD points to at launch—the latest commit, rather than the last time you saved a file in your editor. This command does not transfer uncommitted changes or new files. Saving in your editor is not the same as committing in Git. If the first folder still contains uncommitted changes when you launch the second task, those changes will remain only in that folder. This is not a backup of the entire repository or isolation of the entire computer. It is a second working folder of the same project, with access to the same branch and commit history. For a similar mechanism in another tool, see [Claude Code and git worktree: parallel tasks](https://ailoot.ai/blog/en/claude-code-git-worktree/). ## Preparation: version, project trust, and a commit Check three things before starting. Run the commands from the original project's folder. First, check the Codex CLI version. These instructions apply to version 0.155.1; for other versions, check the behavior of the flags separately: ```bash codex --version ``` Second, you need a local Git project whose HEAD points to an existing commit—in other words, the repository must contain at least one commit. Otherwise, there is nothing to create the copy from. Third, the source must be trusted: if the project is explicitly marked as untrusted, starting with `--worktree` will fail before the copy is created. If you are just setting up Codex CLI, the basic preparation is covered in [Codex (OpenAI): what it is and how to get started](https://ailoot.ai/blog/en/openai-codex-install/). Check the list of this repository's existing working copies beforehand. You can use it for comparison after launching: ```bash git worktree list ``` Separate folders help keep tasks apart. For an overall approach to working with an agent, the practical resources in the [Ailoot documentation](https://ailoot.ai/docs/) are useful. ## Steps: start a separate copy for a second task 1. ### Enable the experimental feature and start a session with a separate copy Run the command from the original project's folder, where you are already working on the first task. ```bash codex --enable worktrees --worktree ``` Expected result: Codex creates a new working copy of the project from the current HEAD and opens an agent session there. The copy is in a detached HEAD state, with no named branch attached. This is how the flag works in version 0.155.1. 2. ### List the working copies again in another terminal in the original project ```bash git worktree list ``` Expected result: the output contains an additional line with the new copy's path and a detached HEAD marker (or a branch, if there is one). This list shows that Git has registered the copy, but it does not confirm that the agent has completed the task. To make sure the files are there, open the folder at the listed path and check its contents. ## How to check the result and preserve your work Once the second task in the new copy is finished, you need to save and transfer the result separately. The `--worktree` command does not merge changes into the main branch or transfer the result automatically. The copy remains in a detached HEAD state, so making a commit inside it does not, by itself, create a new branch. If you need to preserve those commits, attach them to a branch or transfer them to the main project before deleting the copy's folder. Do not delete the copy's folder until the result has been preserved. Checking that the working folder is clean is no substitute for preserving the commits you need: they may still have no branch attached. If you are working on tasks in different tools at the same time, plan in advance how to keep them from interfering with one another. Working with two agents together is covered in [Claude Code and Codex together](https://ailoot.ai/blog/en/claude-code-codex-together/). ## If startup was interrupted: where to find the copy Starting with `--worktree` can fail for several reasons: - the feature was not enabled beforehand and the launch command does not include `--enable worktrees`: Codex will refuse to start with the `--worktree` flag; - you are in the wrong folder, or there is no commit: if the current folder is not a Git repository or it does not yet contain any commits, there is nothing to create the copy from; - the project is explicitly marked as an untrusted source: Codex will refuse to start a session with `--worktree`. First make sure you have opened the correct project. Do not change its trust status automatically. If the session did not manage to attach to the newly created copy—for example, because the process was interrupted—the working folder is not deleted automatically. First check the list of working copies, and before deleting anything, make sure no Codex CLI session is still using this copy: ```bash git worktree list ``` Open the folder and save any changes you need before deleting it. The copy may remain even if the agent session did not finish starting. If the copy exists, is no longer needed, and is definitely not being used by any session, remove it manually with `git worktree remove` from the original repository, specifying the folder's path. Do not add `--force`: if the copy contains uncommitted or untracked files, the command will refuse to delete it. If it refuses, check the folder's contents without disabling the safeguard. When updating Codex CLI, check `codex --version` again and repeat the check with `git worktree list`: experimental flags may behave differently between versions. More resources and tools: [Ailoot](https://ailoot.ai/). ## Questions about Codex worktree: a separate working copy for a second task | Ailoot ### Will the second worktree include my unsaved or uncommitted edits? No. In the described CLI version, it starts from the source repository’s HEAD commit. Uncommitted changes and new files stay in the original folder, so saving a file in the editor is not enough to transfer it. ### Is a clean detached worktree safe to delete? A clean folder can still contain commits that have no named branch. Preserve or transfer those commits first, check that no session uses the worktree, then use ordinary Git worktree removal without forcing past safeguards. ## Ailoot · The company and its project portfolio Ailoot combines established operating experience, a large client base, stable service and ongoing KPI control. The company and its project portfolio: millions of customers; monthly sales in the billions. Ailoot brings that operating experience to API access for AI features in customer products, agents, applications and automations.