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
6 10
711## 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
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
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
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.
