app/worktrees.md Codex Docs, 2026-04-08 18:32 UTC → 2026-05-05 23:00 UTC

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.

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 

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

59 80 

60Remember, 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.

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 

72![Handoff dialog moving a thread from a worktree to Local](/images/codex/app/handoff-light.webp)97</div>

98 

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

106 

107</div>

73 108 

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

75 110 

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.

89 124 

90### Branch limitations125### Branch limitations

91 126 

99 134 

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

101 136 

102Why this limitation exists137<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.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.

105 139 

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

107 141 

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

109 143 

144</ToggleSection>

145 

110### Worktree cleanup146### Worktree cleanup

111 147 

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

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 thread between Local and Worktree?172<ToggleSection title="Can I move a thread between Local and Worktree?">

137 

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

139 checkout and a worktree. Codex handles the Git operations needed to move the174 checkout and a worktree. Codex handles the Git operations needed to move the

140 thread safely between environments. If you hand a thread back to a worktree175 thread safely between environments. If you hand a thread back to a worktree

141 later, Codex returns it to the same associated worktree.176 later, Codex returns it to the same associated worktree.

177</ToggleSection>

142 178 

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

144 

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

146 is deleted. For Codex-managed worktrees, Codex saves a snapshot before181 is deleted. For Codex-managed worktrees, Codex saves a snapshot before

147 deleting the worktree and offers to restore it if you reopen the associated182 deleting the worktree and offers to restore it if you reopen the associated

148 thread. Permanent worktrees are not automatically deleted when you archive183 thread. Permanent worktrees are not automatically deleted when you archive

149 their threads.184 their threads.

185</ToggleSection>