OpenAI - Codex Docs Changes 2026-03-03 18:20 UTC → 2026-03-05 06:22 UTC

4 4 

5ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. Learn more about [what's included](https://developers.openai.com/codex/pricing).5ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. Learn more about [what's included](https://developers.openai.com/codex/pricing).

6 6 

7![Codex app for Windows showing a project sidebar, active thread, and review pane](/images/codex/windows/codex-windows-light.webp)

8 

7![Codex app window with a project sidebar, active thread, and review pane](/images/codex/app/app-screenshot-light.webp)9![Codex app window with a project sidebar, active thread, and review pane](/images/codex/app/app-screenshot-light.webp)

8 10 

9## Getting started11## Getting started

12 14 

131. Download and install the Codex app151. Download and install the Codex app

14 16 

15 The Codex app is currently only available for macOS.17 Download the Codex app for Windows or macOS.

16 18 

17 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)19 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)

18 20 

19 [Get notified for Windows and Linux](https://openai.com/form/codex-app/)21 [Get notified for Linux](https://openai.com/form/codex-app/)

202. Open Codex and sign in222. Open Codex and sign in

21 23 

22 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.24 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.

101 101 

102![Integrated terminal drawer open beneath a Codex thread](/images/codex/app/integrated-terminal-light.webp)102![Integrated terminal drawer open beneath a Codex thread](/images/codex/app/integrated-terminal-light.webp)

103 103 

104## Native Windows sandbox

105 

106On Windows, Codex can run natively in PowerShell with a native Windows sandbox

107instead of requiring WSL or a virtual machine. This lets you stay in

108Windows-native workflows while keeping bounded permissions in place.

109 

110[Learn more about Windows setup and sandboxing](https://developers.openai.com/codex/app/windows).

111 

112![Codex app Windows sandbox setup prompt above the message composer](/images/codex/windows/windows-sandbox-setup.webp)

113 

104## Voice dictation114## Voice dictation

105 115 

106Use your voice to prompt Codex. Hold <kbd>Ctrl</kbd>+<kbd>M</kbd> while the composer is visible and start talking. Your voice will be transcribed. Edit the transcribed prompt or hit send to have Codex start work.116Use your voice to prompt Codex. Hold <kbd>Ctrl</kbd>+<kbd>M</kbd> while the composer is visible and start talking. Your voice will be transcribed. Edit the transcribed prompt or hit send to have Codex start work.

32### Only some threads appear in the sidebar32### Only some threads appear in the sidebar

33 33 

34The sidebar allows filtering of threads depending on the state of a project. If34The sidebar allows filtering of threads depending on the state of a project. If

35you’re missing threads, check whether you have any filters applied by clicking35you're missing threads, click the filter icon next to the **Threads** label and

36the filter icon next to the **Threads** label.36switch to Chronological. If you still don't see the thread, open

37[Settings](codex://settings) and check the archived chats or archived threads

38section.

37 39 

38### Code doesn't run on a worktree40### Code doesn't run on a worktree

39 41 

1# Codex app1# Windows

2 2 

3The Codex app is a focused desktop experience for working on Codex threads in parallel, with built-in worktree support, automations, and Git functionality.3The [Codex app for Windows](https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US) gives you one interface for

4working across projects, running parallel agent threads, and reviewing results.

5It runs natively on Windows using PowerShell and the

6[Windows sandbox](https://developers.openai.com/codex/windows#windows-sandbox), or you can configure it to

7run in [Windows Subsystem for Linux (WSL)](#windows-subsystem-for-linux-wsl).

4 8 

5ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex. Learn more about [what’s included](https://developers.openai.com/codex/pricing).9![Codex app for Windows showing a project sidebar, active thread, and review pane](/images/codex/windows/codex-windows-light.webp)

6 10 

7![Codex app window with a project sidebar, active thread, and review pane](/images/codex/app/app-screenshot-light.webp)11## Download and update the Codex app

8 12 

9## Getting started13Download the Codex app from the

14[Microsoft Store](https://apps.microsoft.com/detail/9plm9xgg6vks?hl=en-US&gl=US).

10 15 

11The Codex app is available on macOS (Apple Silicon).16Then follow the [quickstart](https://developers.openai.com/codex/quickstart?setup=app) to get started.

12 17 

131. Download and install the Codex app18To update the app, open the Microsoft Store, go to **Downloads**, and click

19**Check for updates**. The Store installs the latest version afterward.

14 20 

15 The Codex app is currently only available for macOS.21For enterprises, administrators can deploy the app with Microsoft Store app

22distribution through enterprise management tools.

16 23 

17 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)24If you prefer a command-line install path, or need an alternative to opening

25the Microsoft Store UI, run:

18 26 

19 [Get notified for Windows and Linux](https://openai.com/form/codex-app/)27```powershell

202. Open Codex and sign in28winget install --id 9PLM9XGG6VKS

29```

21 30 

22 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.31## Customize for your dev setup

23 32 

24 If you sign in with an OpenAI API key, some functionality such as [cloud threads](https://developers.openai.com/codex/prompting#threads) might not be available.33### Preferred editor

253. Select a project

26 34 

27 Choose a project folder that you want Codex to work in.35Choose a default app for **Open**, such as Visual Studio, VS Code, or another

36editor. You can override that choice per project. If you already picked a

37different app from the **Open** menu for a project, that project-specific

38choice takes precedence.

28 39 

29If you used the Codex app, CLI, or IDE Extension before you’ll see past projects that you worked on.40![Codex app settings showing the default Open In app on Windows](/images/codex/windows/open-in-windows-light.webp)

30 41 

314. Send your first message42### Integrated terminal

32 43 

33 After choosing the project, make sure **Local** is selected to have Codex work on your machine and send your first message to Codex.44You can also choose the default integrated terminal. Depending on what you have

45installed, options include:

34 46 

35 You can ask Codex anything about the project or your computer in general. Here are some examples:47- PowerShell

48- Command Prompt

49- Git Bash

50- WSL

36 51 

37- Tell me about this project52This change applies only to new terminal sessions. If you already have an

38- Build a classic Snake game in this repo.53integrated terminal open, restart the app or start a new thread before

39- Find and fix bugs in my codebase with minimal, high-confidence changes.54expecting the new default terminal to appear.

40 55 

41 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).56![Codex app settings showing the integrated terminal selection on Windows](/images/codex/windows/integrated-shell-light.webp)

42 57 

58## Windows Subsystem for Linux (WSL)

43 59 

44## Work with the Codex app60By default, the Codex app uses the Windows-native agent. That means the agent

61runs commands in PowerShell. The app can still work with projects that live in

62Windows Subsystem for Linux (WSL) by using the `wsl` CLI when needed.

45 63 

46[### Multitask across projects64If you want to add a project from the WSL filesystem, click **Add new project**

65or press <kbd>Ctrl</kbd>+<kbd>O</kbd>, then type `\\wsl$\` into the File

66Explorer window. From there, choose your Linux distribution and the folder you

67want to open.

47 68 

48Run multiple tasks in parallel and switch quickly between them.](https://developers.openai.com/codex/app/features#multitask-across-projects)[### Built-in Git tools69If you plan to keep using the Windows-native agent, prefer storing projects on

70your Windows filesystem and accessing them from WSL through

71`/mnt/<drive>/...`. This setup is more reliable than opening projects

72directly from the WSL filesystem.

49 73 

50Review diffs, comment inline, stage or revert chunks, and commit without leaving the app.](https://developers.openai.com/codex/app/features#built-in-git-tools)[### Worktrees for parallel tasks74If you want the agent itself to run in WSL, open **[Settings](codex://settings)**,

75switch the agent from Windows native to WSL, and **restart the app**. The

76change doesn't take effect until you restart. Your projects should remain in

77place after restart.

51 78 

52Isolate changes of multiple Codex threads using built-in Git worktree support.](https://developers.openai.com/codex/app/worktrees)[### Skills support79![Codex app settings showing the agent selector with Windows native and WSL options](/images/codex/windows/wsl-select-light.webp)

53 80 

54Give your Codex agent additional capabilities and reuse skills across App, CLI, and IDE Extension.](https://developers.openai.com/codex/app/features#skills-support)[### Automations81You configure the integrated terminal independently from the agent. See

82[Customize for your dev setup](#customize-for-your-dev-setup) for the

83terminal options. You can keep the agent in WSL and still use PowerShell in the

84terminal, or use WSL for both, depending on your workflow.

55 85 

56Pair skills with automations to automate recurring tasks in the background. Codex adds findings to the inbox, or automatically archives runs if there’s nothing to report.](https://developers.openai.com/codex/app/automations)[### Built-in terminal86## Useful developer tools

57 87 

58Open a terminal per thread to test your changes, run dev servers, scripts, and custom commands.](https://developers.openai.com/codex/app/features#integrated-terminal)[### Local environments88Codex works best when a few common developer tools are already installed:

59 89 

60Define worktree setup scripts and common project actions for easy access.](https://developers.openai.com/codex/app/local-environments)[### Sync with the IDE extension90- **Git**: Powers the review panel in the Codex app and lets you inspect or

91 revert changes.

92- **Node.js**: A common tool that the agent uses to perform tasks more

93 efficiently.

94- **Python**: A common tool that the agent uses to perform tasks more

95 efficiently.

96- **.NET SDK**: Useful when you want to build native Windows apps.

97- **GitHub CLI**: Powers GitHub-specific functionality in the Codex app.

61 98 

62Share Auto Context and active threads across app and IDE sessions.](https://developers.openai.com/codex/app/features#sync-with-the-ide-extension)[### MCP support99Install them with the default Windows package manager `winget` by pasting this

100into the [integrated terminal](https://developers.openai.com/codex/app/features#integrated-terminal) or

101asking Codex to install them:

63 102 

64Connect your Codex agent to additional services using MCP.](https://developers.openai.com/codex/app/features#mcp-support)103```powershell

104winget install --id Git.Git

105winget install --id OpenJS.NodeJS.LTS

106winget install --id Python.Python.3.14

107winget install --id Microsoft.DotNet.SDK.10

108winget install --id GitHub.cli

109```

65 110 

111After installing GitHub CLI, run `gh auth login` to enable GitHub features in

112the app.

66 113 

67Need help? Visit the [troubleshooting guide](https://developers.openai.com/codex/app/troubleshooting).114If you need a different Python or .NET version, change the package IDs to the

115version you want.

116 

117## Troubleshooting and FAQ

118 

119### Run commands with elevated permissions

120 

121If you need Codex to run commands with elevated permissions, start the Codex app

122itself as an administrator. After installation, open the Start menu, find

123Codex, and choose Run as administrator. The Codex agent inherits that

124permission level.

125 

126### PowerShell execution policy blocks commands

127 

128If you have never used tools such as Node.js or `npm` in PowerShell before, the

129Codex agent or integrated terminal may hit execution policy errors.

130 

131This can also happen if Codex creates PowerShell scripts for you. In that case,

132you may need a less restrictive execution policy before PowerShell will run

133them.

134 

135An error may look something like this:

136 

137```text

138npm.ps1 cannot be loaded because running scripts is disabled on this system.

139```

140 

141A common fix is to set the execution policy to `RemoteSigned`:

142 

143```powershell

144Set-ExecutionPolicy -ExecutionPolicy RemoteSigned

145```

146 

147For details and other options, check Microsoft's

148[execution policy guide](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies)

149before changing the policy.

150 

151### Local environment scripts on Windows

152 

153If your [local environment](https://developers.openai.com/codex/app/local-environments) uses cross-platform

154commands such as `npm` scripts, you can keep one shared setup script or

155set of actions for every platform.

156 

157If you need Windows-specific behavior, create Windows-specific setup scripts or

158Windows-specific actions.

159 

160Actions run in the environment used by your integrated terminal. See

161[Customize for your dev setup](#customize-for-your-dev-setup).

162 

163Local setup scripts run in the agent environment: WSL if the agent uses WSL,

164and PowerShell otherwise.

165 

166### Share config, auth, and sessions with WSL

167 

168The Windows app uses the same Codex home directory as native Codex on Windows:

169`%USERPROFILE%\.codex`.

170 

171If you also run the Codex CLI inside WSL, the CLI uses the Linux home

172directory by default, so it does not automatically share configuration, cached

173auth, or session history with the Windows app.

174 

175To share them, use one of these approaches:

176 

177- Sync WSL `~/.codex` with `%USERPROFILE%\.codex` on your file system.

178- Point WSL at the Windows Codex home directory by setting `CODEX_HOME`:

179 

180```bash

181export CODEX_HOME=/mnt/c/Users/<windows-user>/.codex

182```

183 

184If you want that setting in every shell, add it to your WSL shell profile, such

185as `~/.bashrc` or `~/.zshrc`.

186 

187### Git features are unavailable

188 

189If you don't have Git installed natively on Windows, the app can't use some

190features. Install it with `winget install Git.Git` from PowerShell or `cmd.exe`.

191 

192### Git isn't detected for projects opened from `\\wsl$`

193 

194For now, if you want to use the Windows-native agent with a project that is

195also accessible from WSL, the most reliable workaround is to store the project

196on the native Windows drive and access it in WSL through `/mnt/<drive>/...`.

197 

198### Cmder is not listed in the open dialog

199 

200If Cmder is installed but doesn’t show in Codex’s open dialog, add it to the

201Windows Start Menu: right-click Cmder and choose **Add to Start**, then restart

202Codex or reboot.

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 

313. Submit your prompt323. Submit your prompt

32 33 

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

344. Verify your changes354. Choose where to keep working

35 36 

36 When you’re ready, follow one of the paths [below](#verifying-and-pushing-workflow-changes)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 based on your project and flow.

38 38 

39## Verifying and pushing workflow changes39## Working between Local and Worktree

40 40 

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

42 42 

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

45In practice, there are two common paths:

44 46 

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

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

47 49 

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

49 51 

57 59 

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

59 61 

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

61 

62### Option 2: Working in your local checkout

63 63 

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

65 65 

66You will be presented with the option of creating a new branch or syncing to an existing branch.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.

67 67 

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:68Codex handles the Git steps required to move the thread safely between the worktree and your local checkout.

69 69 

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

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 71 

73![Sync worktree dialog with options to apply or pull changes](/images/codex/app/sync-worktree-light.webp)72![Handoff dialog moving a thread from a worktree to Local](/images/codex/app/handoff-light.webp)

74 73 

75You can create multiple worktrees and sync them to the same feature branch to split up your work into parallel threads.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.

76 75 

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

78 77 

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

80 79 

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

82 81 

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

84 83 

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

86 85 

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

88 87 

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

90 89 

91### Branch limitations90### Branch limitations

92 91 

98 97 

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

100 99 

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

102 101 

103Why this limitation exists102Why this limitation exists

104 103 

112 111 

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

114 113 

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

116 115 

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

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

119 117 

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

121 121 

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

123- You have more than 10 worktrees

124 123 

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

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

126 126 

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

128 128 

129## Frequently asked questions129## Frequently asked questions

130 130 

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

134 manage them consistently.134 manage them consistently.

135 135 

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

137 137 

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

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

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

141 142 

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

143 144 

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

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

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

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

149 their threads.

125# - danger-full-access (no sandbox; extremely risky)125# - danger-full-access (no sandbox; extremely risky)

126sandbox_mode = "read-only"126sandbox_mode = "read-only"

127 127 

128[windows]

129# Native Windows sandbox mode (Windows only): unelevated | elevated

130sandbox = "unelevated"

131 

128################################################################################132################################################################################

129# Authentication & Login133# Authentication & Login

130################################################################################134################################################################################

50 50 

51API Access51API Access

52 52 

53The gpt-5.3-codex-spark model is available in research preview for ChatGPT Pro

54subscribers. It is optimized for near-instant, real-time coding iteration.

55 

56## Alternative models

57 

53![gpt-5.2-codex](/images/codex/gpt-5.2-codex.png)58![gpt-5.2-codex](/images/codex/gpt-5.2-codex.png)

54 59 

55gpt-5.2-codex60gpt-5.2-codex

60 65 

61Copy command66Copy command

62 67 

63Capability68Show details

64 

65Speed

66 

67Codex CLI & SDK

68 

69Codex app & IDE extension

70 

71Codex Cloud

72 

73ChatGPT Credits

74 

75API Access

76 

77For most coding tasks in Codex, start with gpt-5.3-codex. It is available for

78ChatGPT-authenticated Codex sessions in the Codex app, CLI, IDE extension, and

79Codex Cloud. API access for GPT-5.3-Codex will come soon. The

80gpt-5.3-codex-spark model is available in research preview for ChatGPT Pro

81subscribers.

82 

83## Alternative models

84 69 

85![gpt-5.2](/images/api/models/gpt-5.2.jpg)70![gpt-5.2](/images/api/models/gpt-5.2.jpg)

86 71 

14 14 

151. Download and install the Codex app151. Download and install the Codex app

16 16 

17 The Codex app is currently only available for macOS.17 Download the Codex app for Windows or macOS.

18 18 

19 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)19 [Download for macOS](https://persistent.oaistatic.com/codex-app-prod/Codex.dmg)

20 20 

21 [Get notified for Windows and Linux](https://openai.com/form/codex-app/)21 [Get notified for Linux](https://openai.com/form/codex-app/)

222. Open Codex and sign in222. Open Codex and sign in

23 23 

24 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.24 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.

67 67 

68## Install skills68## Install skills

69 69 

70To install skills beyond the built-ins, use `$skill-installer`:70To install skills beyond the built-ins, use `$skill-installer`. For example, to install the `$linear` skill:

71 71 

72```bash72```bash

73$skill-installer install the linear skill from the .experimental folder73$skill-installer linear

74```74```

75 75 

76You can also prompt the installer to download skills from other repositories. Codex detects newly installed skills automatically; if one doesn’t appear, restart Codex.76You can also prompt the installer to download skills from other repositories. Codex detects newly installed skills automatically; if one doesn’t appear, restart Codex.

1# Windows1# Windows

2 2 

3The easiest way to use Codex on Windows is to [set up the IDE extension](https://developers.openai.com/codex/ide) or [install the CLI](https://developers.openai.com/codex/cli) and run it from PowerShell.3The easiest way to use Codex on Windows is to use the [Codex app](https://developers.openai.com/codex/app/windows). You can also [set up the IDE extension](https://developers.openai.com/codex/ide) or [install the CLI](https://developers.openai.com/codex/cli) and run it from PowerShell.

4 

5[![](/images/codex/codex-banner-icon.webp)

6 

7Use the Codex app on Windows

8 

9Work across projects, run parallel agent threads, and review results in one place with the native Windows app.](https://developers.openai.com/codex/app/windows)

4 10 

5When you run Codex natively on Windows, agent mode uses a [Windows sandbox](#windows-sandbox) to block filesystem writes outside the working folder and prevent network access without your explicit approval. [Learn more below](#windows-sandbox).11When you run Codex natively on Windows, agent mode uses a [Windows sandbox](#windows-sandbox) to block filesystem writes outside the working folder and prevent network access without your explicit approval. [Learn more below](#windows-sandbox).

6 12