app/worktrees.md Codex Docs, 2026-02-19 20:53 UTC → 2026-05-12 01:59 UTC

1# Worktrees1# 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.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 

10 10 

11- **Local checkout**: The repository that you created. Sometimes just referred to as **Local** in the Codex app.11- **Local checkout**: The repository that you created. Sometimes just referred to as **Local** in the Codex app.

12- **Worktree**: A [Git worktree](https://git-scm.com/docs/git-worktree) that was created from your local checkout in the Codex app.12- **Worktree**: A [Git worktree](https://git-scm.com/docs/git-worktree) that was created from your local checkout in the Codex app.

13- **Handoff**: The flow that moves a thread between Local and Worktree. Codex handles the Git operations required to move your work safely between them.

13 14 

14## Why use a worktree15## Why use a worktree

15 16 

161. Work in parallel with Codex without breaking each other as you work.171. Work in parallel with Codex without disturbing your current Local setup.

172. Start a thread unrelated to your current work182. Queue up background work while you stay focused on the foreground.

18 - Staging area to queue up work you want Codex to start but aren’t ready to test yet.193. Move a thread into Local later when you're ready to inspect, test, or collaborate more directly.

19 20 

20## Getting started21## Getting started

21 22 

22Worktrees 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.

23 24 

241. Select “Worktree”25<WorkflowSteps variant="headings">

26 

271. Select "Worktree"

25 28 

26 In the new thread view, select **Worktree** under the composer.29 In the new thread view, select **Worktree** under the composer.

27 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.

313. Submit your prompt363. Submit your prompt

32 37 

33 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).

344. Verify your changes

35 39 

36 When you’re ready, follow one of the paths [below](#verifying-and-pushing-workflow-changes)404. Choose where to keep working

37 based on your project and flow.41 

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## Verifying and pushing workflow changes46## Working between Local and Worktree

40 47 

41Worktrees look and feel much like your local checkout. But **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.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 

43Because of this, choose how you want to verify and commit changes Codex made on a worktree: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.

51 

52In practice, there are two common paths:

44 53 

451. [Work exclusively on the worktree](#option-1-working-on-the-worktree). This path works best when you can verify changes directly on the worktree, for example because you have dependencies and tools installed using a [local environment setup script](https://developers.openai.com/codex/app/local-environments).541. [Work exclusively on the worktree](#option-1-working-on-the-worktree). This path works best when you can verify changes directly on the worktree, for example because you have dependencies and tools installed using a [local environment setup script](https://developers.openai.com/codex/app/local-environments).

462. [Work in your local checkout](#option-2-working-in-your-local-checkout). Use this when you need to bring changes back into your main checkout, for example because you can run only one instance of your app.552. [Hand the thread off to Local](#option-2-handing-a-thread-off-to-local). Use this when you want to bring the thread into the foreground, for example because you want to inspect changes in your usual IDE or can run only one instance of your app.

47 56 

48### Option 1: Working on the worktree57### Option 1: Working on the worktree

49 58 

59<div class="feature-grid">

60 

61<div>

62 

50If 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.

51 64 

52From 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.

53 66 

54You 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.

55 68 

56![Worktree thread view with branch controls and worktree details](/images/codex/app/worktree-light.webp)69</div>

70 

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>

57 80 

58Remember, if you create a branch on a worktree, you can't check it out in any other worktree, including your local checkout.81Remember, if you create a branch on a worktree, you can't check it out in any other worktree, including your local checkout.

59 82 

60If you plan to keep working on this branch, you can [add it to the sidebar](#adding-a-worktree-to-the-sidebar). Otherwise, archive the thread after you’re done so the worktree can be deleted.83### Option 2: Handing a thread off to Local

61 84 

62### Option 2: Working in your local checkout85<div class="feature-grid">

63 86 

64If you don’t want to verify your changes directly on the worktree and instead check them out on your local checkout, click **Sync with local** in the header of your thread.87<div>

65 88 

66You will be presented with the option of creating a new branch or syncing to an existing branch.89If you want to bring a thread into the foreground, click **Hand off** in the header of your thread and move it to **Local**.

67 90 

68You can sync with local at any point. To do so, click **Sync with local** in the header again. From here, you can choose which direction to sync (to local or from local) and a sync method: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 92 

70- **Overwrite**: Makes the destination checkout match the source checkout’s files and commit history.93Codex handles the Git steps required to move the thread safely between the worktree and your local checkout.

71- **Apply**: Calculates the source changes since the nearest shared commit and applies that patch onto the destination checkout, preserving destination commit history while bringing over source code changes (not source commits).

72 94 

73![Sync worktree dialog with options to apply or pull changes](/images/codex/app/sync-worktree-light.webp)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.

74 96 

75You can create multiple worktrees and sync them to the same feature branch to split up your work into parallel threads.97</div>

76 98 

77In some cases, changes on your worktree might conflict with changes on your local checkout, for example from testing a previous worktree. In those cases, you can use the **Overwrite local** option to reset the previous changes and cleanly apply your worktree changes.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/>

78 106 

79Since this process uses Git operations, any files that are part of the `.gitignore` file won’t be transferred during the sync process.107</div>

80 108 

81## Adding a worktree to the sidebar109You 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.

82 110 

83If you choose option one above (work on the worktree), once you have created a branch on the worktree, an option appears in the header to add the worktree to your sidebar. This promotes the worktree to a permanent home. When you do this, it will never be automatically deleted, and you can even kick off new threads from the same worktree.111Since Handoff uses Git operations, any files that are part of your `.gitignore` file won't move with the thread.

84 112 

85## Advanced details113## Advanced details

86 114 

115### Codex-managed and permanent worktrees

116 

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.

118 

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 are not automatically deleted, and you can start multiple threads from the same worktree.

120 

87### How Codex manages worktrees for you121### How Codex manages worktrees for you

88 122 

89Codex will create a worktree 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 means you can 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.

90 124 

91### Branch limitations125### Branch limitations

92 126 

98 132 

99To resolve this, you would need to check out another branch instead of `feature/a` on the worktree.133To resolve this, you would need to check out another branch instead of `feature/a` on the worktree.

100 134 

101If you plan on checking out the branch locally, try Workflow 2 ([sync with local](#option-2-working-in-your-local-checkout)).135If 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.

102 

103Why this limitation exists

104 136 

137<ToggleSection title="Why this limitation exists">

105Git 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.138Git 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.

106 139 

107When 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.140When 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.

108 141 

109By 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.142By 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.

110 143 

144</ToggleSection>

145 

111### Worktree cleanup146### Worktree cleanup

112 147 

113Worktrees 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.148Worktrees 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.

114 149 

115Worktrees will never be cleaned up if:150By 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.

116 151 

117- A pinned conversation is tied to it152Codex tries to avoid deleting worktrees that are still important. Codex-managed worktrees won't be deleted automatically if:

118- The worktree was added to the sidebar (see above)

119 153 

120Worktrees are eligible for cleanup when:154- A pinned conversation is tied to it

155- The thread is still in progress

156- The worktree is a permanent worktree

121 157 

122- It’s more than 4 days old158Codex-managed worktrees are deleted automatically when:

123- You have more than 10 worktrees

124 159 

125When either of those conditions are met, Codex automatically cleans up a worktree when you archive a thread, or on app startup if it finds a worktree with no associated threads.160- You archive the associated thread

161- Codex needs to delete older worktrees to stay within your configured limit

126 162 

127Before cleaning up a worktree, Codex will save a snapshot of the work on it that you can restore at any point in a new worktree. If you open a conversation after its worktree was cleaned up, you’ll see the option to restore it.163Before 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 164 

129## Frequently asked questions165## Frequently asked questions

130 166 

131Can I control where worktrees are created?167<ToggleSection title="Can I control where worktrees are created?">

132 

133 Not today. Codex creates worktrees under `$CODEX_HOME/worktrees` so it can168 Not today. Codex creates worktrees under `$CODEX_HOME/worktrees` so it can

134 manage them consistently.169 manage them consistently.

170</ToggleSection>

135 171 

136Can I move a session between worktrees?172<ToggleSection title="Can I move a thread between Local and Worktree?">

137 173 Yes. Use **Hand off** in the thread header to move a thread between your local

138Not yet. If you need to change environments, you have to start a new thread in174 checkout and a worktree. Codex handles the Git operations needed to move the

139the target environment and restate the prompt. You can use the up arrow keys175 thread safely between environments. If you hand a thread back to a worktree

140in the composer to try to recover your prompt.176 later, Codex returns it to the same associated worktree.

141 177</ToggleSection>

142What happens to threads if a worktree is deleted?

143 178 

179<ToggleSection title="What happens to threads if a worktree is deleted?">

144 Threads can remain in your history even if the underlying worktree directory180 Threads can remain in your history even if the underlying worktree directory

145is cleaned up. However, Codex saves a snapshot of the worktree prior to181 is deleted. For Codex-managed worktrees, Codex saves a snapshot before

146cleaning it up and offers to restore it if you reopen the thread associated182 deleting the worktree and offers to restore it if you reopen the associated

147with it.183 thread. Permanent worktrees are not automatically deleted when you archive

184 their threads.

185</ToggleSection>