1# Worktrees – Codex app1# Worktrees
2 2
3In the Codex app, worktrees let Codex run multiple independent tasks in the same project without interfering with each other. For Git repositories, [automations](https://developers.openai.com/codex/app/automations) run on dedicated background worktrees so they don’t conflict with your ongoing work. In non-version-controlled projects, automations run directly in the project directory. You can also start threads on a worktree manually, and use Handoff to move a thread between Local and Worktree.3In the Codex app, worktrees let Codex run multiple independent tasks in the same project without interfering with each other. For Git repositories, [automations](https://developers.openai.com/codex/app/automations) run on dedicated background worktrees so they don't conflict with your ongoing work. In non-version-controlled projects, automations run directly in the project directory. You can also start threads on a worktree manually, and use Handoff to move a thread between Local and Worktree.
4 4
5## What’s a worktree5## What's a worktree
6 6
7Worktrees only work in projects that are part of a Git repository since they use [Git worktrees](https://git-scm.com/docs/git-worktree) under the hood. A worktree allows you to create a second copy (“checkout”) of your repository. Each worktree has its own copy of every file in your repo but they all share the same metadata (`.git` folder) about commits, branches, etc. This allows you to check out and work on multiple branches in parallel.7Worktrees only work in projects that are part of a Git repository since they use [Git worktrees](https://git-scm.com/docs/git-worktree) under the hood. A worktree allows you to create a second copy ("checkout") of your repository. Each worktree has its own copy of every file in your repo but they all share the same metadata (`.git` folder) about commits, branches, etc. This allows you to check out and work on multiple branches in parallel.
8 8
9## Terminology9## Terminology
10 10
16 16
171. Work in parallel with Codex without disturbing your current Local setup.171. Work in parallel with Codex without disturbing your current Local setup.
182. Queue up background work while you stay focused on the foreground.182. Queue up background work while you stay focused on the foreground.
193. Move a thread into Local later when you’re ready to inspect, test, or collaborate more directly.193. Move a thread into Local later when you're ready to inspect, test, or collaborate more directly.
20 20
21## Getting started21## Getting started
22 22
23Worktrees require a Git repository. Make sure the project you selected lives in one.23Worktrees require a Git repository. Make sure the project you selected lives in one.
24 24
251. Select “Worktree”25<WorkflowSteps variant="headings">
26
271. Select "Worktree"
26 28
27 In the new thread view, select **Worktree** under the composer.29 In the new thread view, select **Worktree** under the composer.
28 Optionally, choose a [local environment](https://developers.openai.com/codex/app/local-environments) to run setup scripts for the worktree.30 Optionally, choose a [local environment](https://developers.openai.com/codex/app/local-environments) to run setup scripts for the worktree.
292. Select the starting branch322. Select the starting branch
30 33
31 Below the composer, choose the Git branch to base the worktree on. This can be your `main` / `master` branch, a feature branch, or your current branch with unstaged local changes.34 Below the composer, choose the Git branch to base the worktree on. This can be your `main` / `master` branch, a feature branch, or your current branch with unstaged local changes.
35
323. Submit your prompt363. Submit your prompt
33 37
34 Submit your task and Codex will create a Git worktree based on the branch you selected. By default, Codex works in a [“detached HEAD”](https://git-scm.com/docs/git-checkout#_detached_head).38 Submit your task and Codex will create a Git worktree based on the branch you selected. By default, Codex works in a ["detached HEAD"](https://git-scm.com/docs/git-checkout#_detached_head).
39
354. Choose where to keep working404. Choose where to keep working
36 41
37 When you’re ready, you can either keep working directly on the worktree or hand the thread off to your local checkout. Handing off to or from local will move your thread *and* code so you can continue in the other checkout.42 When you're ready, you can either keep working directly on the worktree or hand the thread off to your local checkout. Handing off to or from local will move your thread _and_ code so you can continue in the other checkout.
43
44</WorkflowSteps>
38 45
39## Working between Local and Worktree46## Working between Local and Worktree
40 47
41Worktrees look and feel much like your local checkout. The difference is where they fit into your flow. You can think of Local as the foreground and Worktree as the background. Handoff lets you move a thread between them.48Worktrees look and feel much like your local checkout. The difference is where they fit into your flow. You can think of Local as the foreground and Worktree as the background. Handoff lets you move a thread between them.
42 49
43Under the hood, Handoff handles the Git operations required to move work between two checkouts safely. This matters because **Git only allows a branch to be checked out in one place at a time**. If you check out a branch on a worktree, you **can’t** check it out in your local checkout at the same time, and vice versa.50Under the hood, Handoff handles the Git operations required to move work between two checkouts safely. This matters because **Git only allows a branch to be checked out in one place at a time**. If you check out a branch on a worktree, you **can't** check it out in your local checkout at the same time, and vice versa.
44 51
45In practice, there are two common paths:52In practice, there are two common paths:
46 53
49 56
50### Option 1: Working on the worktree57### Option 1: Working on the worktree
51 58
59<div class="feature-grid">
60
61<div>
62
52If you want to stay exclusively on the worktree with your changes, turn your worktree into a branch using the **Create branch here** button in the header of your thread.63If you want to stay exclusively on the worktree with your changes, turn your worktree into a branch using the **Create branch here** button in the header of your thread.
53 64
54From here you can commit your changes, push your branch to your remote repository, and open a pull request on GitHub.65From here you can commit your changes, push your branch to your remote repository, and open a pull request on GitHub.
55 66
56You can open your IDE to the worktree using the “Open” button in the header, use the integrated terminal, or anything else that you need to do from the worktree directory.67You can open your IDE to the worktree using the "Open" button in the header, use the integrated terminal, or anything else that you need to do from the worktree directory.
57 68
5869</div>
59 70
60Remember, if you create a branch on a worktree, you can’t check it out in any other worktree, including your local checkout.71<CodexScreenshot
72 alt="Worktree thread view with branch controls and worktree details"
73 lightSrc="/images/codex/app/worktree-light.webp"
74 darkSrc="/images/codex/app/worktree-dark.webp"
75 maxHeight="400px"
76 class="mb-4 lg:mb-0"
77/>
78
79</div>
80
81Remember, if you create a branch on a worktree, you can't check it out in any other worktree, including your local checkout.
61 82
62### Option 2: Handing a thread off to Local83### Option 2: Handing a thread off to Local
63 84
85<div class="feature-grid">
86
87<div>
88
64If you want to bring a thread into the foreground, click **Hand off** in the header of your thread and move it to **Local**.89If you want to bring a thread into the foreground, click **Hand off** in the header of your thread and move it to **Local**.
65 90
66This path works well when you want to read the changes in your usual IDE window, run your existing development server, or validate the work in the same environment you already use day to day.91This path works well when you want to read the changes in your usual IDE window, run your existing development server, or validate the work in the same environment you already use day to day.
69 94
70Each thread keeps the same associated worktree over time. If you hand the thread back to a worktree later, Codex returns it to that same background environment so you can pick up where you left off.95Each thread keeps the same associated worktree over time. If you hand the thread back to a worktree later, Codex returns it to that same background environment so you can pick up where you left off.
71 96
7297</div>
73 98
74You can also go the other direction. If you’re already working in Local and want to free up the foreground, use **Hand off** to move the thread to a worktree. This is useful when you want Codex to keep working in the background while you switch your attention back to something else locally.99<CodexScreenshot
100 alt="Handoff dialog moving a thread from a worktree to Local"
101 lightSrc="/images/codex/app/handoff-light.webp"
102 darkSrc="/images/codex/app/handoff-dark.webp"
103 maxHeight="400px"
104 class="mb-4 lg:mb-0"
105/>
75 106
76Since Handoff uses Git operations, any files that are part of your `.gitignore` file won’t move with the thread.107</div>
108
109You can also go the other direction. If you're already working in Local and want to free up the foreground, use **Hand off** to move the thread to a worktree. This is useful when you want Codex to keep working in the background while you switch your attention back to something else locally.
110
111Since Handoff uses Git operations, any files that are part of your `.gitignore` file won't move with the thread unless Codex copies them into a local managed worktree with `.worktreeinclude`.
77 112
78## Advanced details113## Advanced details
79 114
81 116
82By default, threads use a Codex-managed worktree. These are meant to feel lightweight and disposable. A Codex-managed worktree is typically dedicated to one thread, and Codex returns that thread to the same worktree if you hand it back there later.117By default, threads use a Codex-managed worktree. These are meant to feel lightweight and disposable. A Codex-managed worktree is typically dedicated to one thread, and Codex returns that thread to the same worktree if you hand it back there later.
83 118
84If you want a long-lived environment, create a permanent worktree from the three-dot menu on a project in the sidebar. This creates a new permanent worktree as its own project. Permanent worktrees are not automatically deleted, and you can start multiple threads from the same worktree.119If you want a long-lived environment, create a permanent worktree from the three-dot menu on a project in the sidebar. This creates a new permanent worktree as its own project. Permanent worktrees aren't automatically deleted, and you can start multiple threads from the same worktree.
85 120
86### How Codex manages worktrees for you121### How Codex manages worktrees for you
87 122
88Codex creates worktrees in `$CODEX_HOME/worktrees`. The starting commit will be the `HEAD` commit of the branch selected when you start your thread. If you chose a branch with local changes, the uncommitted changes will be applied to the worktree as well. The worktree will *not* be checked out as a branch. It will be in a [detached HEAD](https://git-scm.com/docs/git-checkout#_detached_head) state. This lets Codex create several worktrees without polluting your branches.123Codex creates worktrees in `$CODEX_HOME/worktrees`. The starting commit will be the `HEAD` commit of the branch selected when you start your thread. If you chose a branch with local changes, the uncommitted changes will be applied to the worktree as well. The worktree will _not_ be checked out as a branch. It will be in a [detached HEAD](https://git-scm.com/docs/git-checkout#_detached_head) state. This lets Codex create several worktrees without polluting your branches.
124
125### Copy ignored local files into managed worktrees
126
127Local Codex-managed worktrees start from a Git checkout, so tracked files are already present. If your repository ignores local setup files that a new worktree needs, add a `.worktreeinclude` file to the repository root and list the ignored paths or `.gitignore`-style patterns to copy when Codex creates a managed worktree.
128
129Use this for files Git intentionally ignores, such as `.env`, `.env.local`, or `config/secrets.json`. Codex only copies ignored files that match `.worktreeinclude`; it doesn't copy other local files that Git doesn't track. Don't list tracked files.
130
131Codex automatically copies an ignored `AGENTS.override.md` into local managed worktrees, so you don't need to list it in `.worktreeinclude`.
132
133```text
134# .worktreeinclude
135.env
136.env.local
137config/secrets.json
138```
139
140Codex skips source symlinks and won't overwrite files that already exist in the new checkout. This behavior applies to local Codex app managed worktrees, not remote worktrees or Git worktrees you create yourself from the command line.
89 141
90### Branch limitations142### Branch limitations
91 143
99 151
100If you plan on checking out the branch locally, use Handoff to move the thread into Local instead of trying to keep the same branch checked out in both places at once.152If you plan on checking out the branch locally, use Handoff to move the thread into Local instead of trying to keep the same branch checked out in both places at once.
101 153
102Why this limitation exists154<ToggleSection title="Why this limitation exists">
103
104Git prevents the same branch from being checked out in more than one worktree at a time because a branch represents a single mutable reference (`refs/heads/<name>`) whose meaning is “the current checked-out state” of a working tree.155Git prevents the same branch from being checked out in more than one worktree at a time because a branch represents a single mutable reference (`refs/heads/<name>`) whose meaning is “the current checked-out state” of a working tree.
105 156
106When a branch is checked out, Git treats its HEAD as owned by that worktree and expects operations like commits, resets, rebases, and merges to advance that reference in a well-defined, serialized way. Allowing multiple worktrees to simultaneously check out the same branch would create ambiguity and race conditions around which worktree’s operations update the branch reference, potentially leading to lost commits, inconsistent indexes, or unclear conflict resolution.157When a branch is checked out, Git treats its HEAD as owned by that worktree and expects operations like commits, resets, rebases, and merges to advance that reference in a well-defined, serialized way. Allowing multiple worktrees to simultaneously check out the same branch would create ambiguity and race conditions around which worktree’s operations update the branch reference, potentially leading to lost commits, inconsistent indexes, or unclear conflict resolution.
107 158
108By enforcing a one-branch-per-worktree rule, Git guarantees that each branch has a single authoritative working copy, while still allowing other worktrees to safely reference the same commits via detached HEADs or separate branches.159By enforcing a one-branch-per-worktree rule, Git guarantees that each branch has a single authoritative working copy, while still allowing other worktrees to safely reference the same commits via detached HEADs or separate branches.
109 160
161</ToggleSection>
162
110### Worktree cleanup163### Worktree cleanup
111 164
112Worktrees can take up a lot of disk space. Each one has its own set of repository files, dependencies, build caches, etc. As a result, the Codex app tries to keep the number of worktrees to a reasonable limit.165Worktrees can take up a lot of disk space. Each one has its own set of repository files, dependencies, build caches, etc. As a result, the Codex app tries to keep the number of worktrees to a reasonable limit.
113 166
114By default, Codex keeps your most recent 15 Codex-managed worktrees. You can change this limit or turn off automatic deletion in settings if you prefer to manage disk usage yourself.167By default, Codex keeps your most recent 15 Codex-managed worktrees. You can change this limit or turn off automatic deletion in settings if you prefer to manage disk usage yourself.
115 168
116Codex tries to avoid deleting worktrees that are still important. Codex-managed worktrees won’t be deleted automatically if:169Codex tries to avoid deleting worktrees that are still important. Codex-managed worktrees won't be deleted automatically if:
117 170
118- A pinned conversation is tied to it171- A pinned conversation is tied to it
119- The thread is still in progress172- The thread is still in progress
124- You archive the associated thread177- You archive the associated thread
125- Codex needs to delete older worktrees to stay within your configured limit178- Codex needs to delete older worktrees to stay within your configured limit
126 179
127Before deleting a Codex-managed worktree, Codex saves a snapshot of the work on it. If you open a conversation after its worktree was deleted, you’ll see the option to restore it.180Before deleting a Codex-managed worktree, Codex saves a snapshot of the work on it. If you open a conversation after its worktree was deleted, you'll see the option to restore it.
128 181
129## Frequently asked questions182## Frequently asked questions
130 183
131Can I control where worktrees are created?184<ToggleSection title="Can I control where worktrees are created?">
132 185 Not today. Codex creates worktrees under `$CODEX_HOME/worktrees` so it can
133Not today. Codex creates worktrees under `$CODEX_HOME/worktrees` so it can186 manage them consistently.
134manage them consistently.187</ToggleSection>
135 188
136Can I move a thread between Local and Worktree?189<ToggleSection title="Can I move a thread between Local and Worktree?">
137 190 Yes. Use **Hand off** in the thread header to move a thread between your local
138Yes. Use **Hand off** in the thread header to move a thread between your local191 checkout and a worktree. Codex handles the Git operations needed to move the
139checkout and a worktree. Codex handles the Git operations needed to move the192 thread safely between environments. If you hand a thread back to a worktree
140thread safely between environments. If you hand a thread back to a worktree193 later, Codex returns it to the same associated worktree.
141later, Codex returns it to the same associated worktree.194</ToggleSection>
142 195
143What happens to threads if a worktree is deleted?196<ToggleSection title="What happens to threads if a worktree is deleted?">
144 197 Threads can remain in your history even if the underlying worktree directory
145Threads can remain in your history even if the underlying worktree directory198 is deleted. For Codex-managed worktrees, Codex saves a snapshot before
146is deleted. For Codex-managed worktrees, Codex saves a snapshot before199 deleting the worktree and offers to restore it if you reopen the associated
147deleting the worktree and offers to restore it if you reopen the associated200 thread. Permanent worktrees are not automatically deleted when you archive
148thread. Permanent worktrees are not automatically deleted when you archive201 their threads.
149their threads.202</ToggleSection>
150
