app/worktrees.md Codex Docs, 2026-02-19 20:37 UTC → 2026-05-13 00:57 UTC

1# Worktrees1# Worktrees

2 2 

3Leverage Git worktrees within the Codex app to let Codex work in parallel3In 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 

5In 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.

6 4 

7## What's a worktree5## What's a worktree

8 6 

12 10 

13- **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.

14- **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.

15 14 

16## Why use a worktree15## Why use a worktree

17 16 

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

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

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

21 20 

22## Getting started21## Getting started

23 22 

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

25 24 

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

26 

271. Select "Worktree"

27 28 

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

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

333. Submit your prompt363. Submit your prompt

34 37 

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

364. Verify your changes

37 39 

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

39 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>

40 45 

41## Verifying and pushing workflow changes46## Working between Local and Worktree

42 47 

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

44 49 

45Because 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:

46 53 

471. [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).

482. [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.

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 

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

59 70 

60![Worktree thread view with branch controls and worktree details](/images/codex/app/worktree-light.webp) ![Worktree thread view with branch controls and worktree details](/images/codex/app/worktree-dark.webp)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/>

61 78 

62Remember, if you create a branch on a worktree, you can't check it out in any other worktree, including your local checkout.79</div>

63 80 

64If 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.81Remember, if you create a branch on a worktree, you can't check it out in any other worktree, including your local checkout.

65 82 

66### Option 2: Working in your local checkout83### Option 2: Handing a thread off to Local

67 84 

68If 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.85<div class="feature-grid">

69 86 

70You will be presented with the option of creating a new branch or syncing to an existing branch.87<div>

71 88 

72You 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:89If you want to bring a thread into the foreground, click **Hand off** in the header of your thread and move it to **Local**.

73 90 

74- **Overwrite**: Makes the destination checkout match the source checkout’s files and commit history.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.

75- **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).

76 92 

77![Sync worktree dialog with options to apply or pull changes](/images/codex/app/sync-worktree-light.webp) ![Sync worktree dialog with options to apply or pull changes](/images/codex/app/sync-worktree-dark.webp)93Codex handles the Git steps required to move the thread safely between the worktree and your local checkout.

78 94 

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

80 96 

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

82 98 

83In 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/>

84 106 

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

86 108 

87## 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.

88 110 

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

90 112 

91## Advanced details113## Advanced details

92 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 

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

94 122 

95Codex 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.

96 124 

97### Branch limitations125### Branch limitations

98 126 

104 132 

105To 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.

106 134 

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

108 

109Why this limitation exists

110 136 

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

111Git 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.

112 139 

113When 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.

114 141 

115By 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.

116 143 

144</ToggleSection>

145 

117### Worktree cleanup146### Worktree cleanup

118 147 

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

120 149 

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

122 151 

123- 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:

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

125 153 

126Worktrees 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

127 157 

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

129- You have more than 10 worktrees

130 159 

131When 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

132 162 

133Before 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.

134 164 

135## Frequently asked questions165## Frequently asked questions

136 166 

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

138 

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

140 manage them consistently.169 manage them consistently.

170</ToggleSection>

141 171 

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

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

144Not 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

145the 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

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

147 177</ToggleSection>

148What happens to threads if a worktree is deleted?

149 178 

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

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

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

152cleaning 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

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

154 184 their threads.

155[Previous185</ToggleSection>

156 

157Automations](https://developers.openai.com/codex/app/automations)[Next

158 

159Local Environments](https://developers.openai.com/codex/app/local-environments)