app/worktrees.md Codex Docs, 2026-02-19 20:37 UTC → 2026-03-31 00:39 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 

333. Submit your prompt323. Submit your prompt

34 33 

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

364. Verify your changes354. Choose where to keep working

36 

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.

37 38 

38 When you’re ready, follow one of the paths [below](#verifying-and-pushing-workflow-changes)39## Working between Local and Worktree

39 based on your project and flow.

40 40 

41## Verifying and pushing workflow changes41Worktrees 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 42 

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

44 44 

45Because of this, choose how you want to verify and commit changes Codex made on a worktree:45In practice, there are two common paths:

46 46 

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

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

50### Option 1: Working on the worktree50### Option 1: Working on the worktree

51 51 

55 55 

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

57 57 

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

59 

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)

61 59 

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

63 61 

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.62### Option 2: Handing a thread off to Local

65 63 

66### Option 2: Working in your local checkout64If you want to bring a thread into the foreground, click **Hand off** in the header of your thread and move it to **Local**.

67 65 

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

69 67 

70You will be presented with the option of creating a new branch or syncing to an existing branch.68Codex handles the Git steps required to move the thread safely between the worktree and your local checkout.

71 69 

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

73 71 

74- **Overwrite**: Makes the destination checkout match the source checkout’s files and commit history.72![Handoff dialog moving a thread from a worktree to Local](/images/codex/app/handoff-light.webp)

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 73 

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

78 75 

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)76Since Handoff uses Git operations, any files that are part of your `.gitignore` file won't move with the thread.

80 77 

81You can create multiple worktrees and sync them to the same feature branch to split up your work into parallel threads.78## Advanced details

82 

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.

84 

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

86 79 

87## Adding a worktree to the sidebar80### Codex-managed and permanent worktrees

88 81 

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

90 83 

91## Advanced details84If 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.

92 85 

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

94 87 

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

96 89 

97### Branch limitations90### Branch limitations

98 91 

104 97 

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

106 99 

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

108 101 

109Why this limitation exists102Why this limitation exists

110 103 

118 111 

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

120 113 

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

122 115 

123- A pinned conversation is tied to it116Codex 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 117 

126Worktrees are eligible for cleanup when:118- A pinned conversation is tied to it

119- The thread is still in progress

120- The worktree is a permanent worktree

127 121 

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

129- You have more than 10 worktrees

130 123 

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.124- You archive the associated thread

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

132 126 

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

134 128 

135## Frequently asked questions129## Frequently asked questions

136 130 

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

140 manage them consistently.134 manage them consistently.

141 135 

142Can I move a session between worktrees?136Can I move a thread between Local and Worktree?

143 137 

144Not yet. If you need to change environments, you have to start a new thread in138 Yes. Use **Hand off** in the thread header to move a thread between your local

145the target environment and restate the prompt. You can use the up arrow keys139 checkout and a worktree. Codex handles the Git operations needed to move the

146in the composer to try to recover your prompt.140 thread safely between environments. If you hand a thread back to a worktree

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

147 142 

148What happens to threads if a worktree is deleted?143What happens to threads if a worktree is deleted?

149 144 

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

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

152cleaning it up and offers to restore it if you reopen the thread associated147 deleting the worktree and offers to restore it if you reopen the associated

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

154 149 their threads.

155[Previous

156 

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

158 

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