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)24## Customize for your dev setup
18 25
19 [Get notified for Windows and Linux](https://openai.com/form/codex-app/)26### Preferred editor
202. Open Codex and sign in
21 27
22 Once you downloaded and installed the Codex app, open it and sign in with your ChatGPT account or an OpenAI API key.28Choose a default app for **Open**, such as Visual Studio, VS Code, or another
29editor. You can override that choice per project. If you already picked a
30different app from the **Open** menu for a project, that project-specific
31choice takes precedence.
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
253. Select a project
26 34
27 Choose a project folder that you want Codex to work in.35### Integrated terminal
28 36
29If you used the Codex app, CLI, or IDE Extension before you’ll see past projects that you worked on.37You can also choose the default integrated terminal. Depending on what you have
38installed, options include:
30 39
314. Send your first message40- PowerShell
41- Command Prompt
42- Git Bash
43- WSL
32 44
33 After choosing the project, make sure **Local** is selected to have Codex work on your machine and send your first message to Codex.45This change applies only to new terminal sessions. If you already have an
46integrated terminal open, restart the app or start a new thread before
47expecting the new default terminal to appear.
34 48
35 You can ask Codex anything about the project or your computer in general. Here are some examples:49
36 50
37- Tell me about this project51## Windows Subsystem for Linux (WSL)
38- Build a classic Snake game in this repo.
39- Find and fix bugs in my codebase with minimal, high-confidence changes.
40 52
41 If you need more inspiration, check out the [explore section](https://developers.openai.com/codex/explore).53By default, the Codex app uses the Windows-native agent. That means the agent
54runs commands in PowerShell. The app can still work with projects that live in
55Windows Subsystem for Linux (WSL) by using the `wsl` CLI when needed.
42 56
57If you want to add a project from the WSL filesystem, click **Add new project**
58or press <kbd>Ctrl</kbd>+<kbd>O</kbd>, then type `\\wsl$\` into the File
59Explorer window. From there, choose your Linux distribution and the folder you
60want to open.
43 61
44## Work with the Codex app62If you plan to keep using the Windows-native agent, prefer storing projects on
63your Windows filesystem and accessing them from WSL through
64`/mnt/<drive>/...`. This setup is more reliable than opening projects
65directly from the WSL filesystem.
45 66
46[### Multitask across projects67If you want the agent itself to run in WSL, open **[Settings](codex://settings)**,
68switch the agent from Windows native to WSL, and **restart the app**. The
69change doesn't take effect until you restart. Your projects should remain in
70place after restart.
47 71
48Run multiple tasks in parallel and switch quickly between them.](https://developers.openai.com/codex/app/features#multitask-across-projects)[### Built-in Git tools72
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 tasks74You configure the integrated terminal independently from the agent. See
75[Customize for your dev setup](#customize-for-your-dev-setup) for the
76terminal options. You can keep the agent in WSL and still use PowerShell in the
77terminal, or use WSL for both, depending on your workflow.
51 78
52Isolate changes of multiple Codex threads using built-in Git worktree support.](https://developers.openai.com/codex/app/worktrees)[### Skills support79## Useful developer tools
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)[### Automations81Codex works best when a few common developer tools are already installed:
55 82
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 terminal83- **Git**: Powers the review panel in the Codex app and lets you inspect or
84 revert changes.
85- **Node.js**: A common tool that the agent uses to perform tasks more
86 efficiently.
87- **Python**: A common tool that the agent uses to perform tasks more
88 efficiently.
89- **.NET SDK**: Useful when you want to build native Windows apps.
90- **GitHub CLI**: Powers GitHub-specific functionality in the Codex app.
57 91
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 environments92Install them with the default Windows package manager `winget` by pasting this
93into the [integrated terminal](https://developers.openai.com/codex/app/features#integrated-terminal) or
94asking Codex to install them:
59 95
60Define worktree setup scripts and common project actions for easy access.](https://developers.openai.com/codex/app/local-environments)[### Sync with the IDE extension96```powershell
97winget install --id Git.Git
98winget install --id OpenJS.NodeJS.LTS
99winget install --id Python.Python.3.14
100winget install --id Microsoft.DotNet.SDK.10
101winget install --id GitHub.cli
102```
61 103
62Share Auto Context and active threads across app and IDE sessions.](https://developers.openai.com/codex/app/features#sync-with-the-ide-extension)[### MCP support104After installing GitHub CLI, run `gh auth login` to enable GitHub features in
105the app.
63 106
64Connect your Codex agent to additional services using MCP.](https://developers.openai.com/codex/app/features#mcp-support)107If you need a different Python or .NET version, change the package IDs to the
108version you want.
65 109
110## Troubleshooting and FAQ
66 111
67Need help? Visit the [troubleshooting guide](https://developers.openai.com/codex/app/troubleshooting).112### Run commands with elevated permissions
113
114If you need Codex to run commands with elevated permissions, start the Codex app
115itself as an administrator. After installation, open the Start menu, find
116Codex, and choose Run as administrator. The Codex agent inherits that
117permission level.
118
119### PowerShell execution policy blocks commands
120
121If you have never used tools such as Node.js or `npm` in PowerShell before, the
122Codex agent or integrated terminal may hit execution policy errors.
123
124This can also happen if Codex creates PowerShell scripts for you. In that case,
125you may need a less restrictive execution policy before PowerShell will run
126them.
127
128An error may look something like this:
129
130```text
131npm.ps1 cannot be loaded because running scripts is disabled on this system.
132```
133
134A common fix is to set the execution policy to `RemoteSigned`:
135
136```powershell
137Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
138```
139
140For details and other options, check Microsoft's
141[execution policy guide](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies)
142before changing the policy.
143
144### Local environment scripts on Windows
145
146If your [local environment](https://developers.openai.com/codex/app/local-environments) uses cross-platform
147commands such as `npm` scripts, you can keep one shared setup script or
148set of actions for every platform.
149
150If you need Windows-specific behavior, create Windows-specific setup scripts or
151Windows-specific actions.
152
153Actions run in the environment used by your integrated terminal. See
154[Customize for your dev setup](#customize-for-your-dev-setup).
155
156Local setup scripts run in the agent environment: WSL if the agent uses WSL,
157and PowerShell otherwise.
158
159### Git features are unavailable
160
161If you don't have Git installed natively on Windows, the app can't use some
162features. Install it with `winget install Git.Git` from PowerShell or `cmd.exe`.
163
164### Cmder is not listed in the open dialog
165
166If Cmder is installed but doesn’t show in Codex’s open dialog, add it to the
167Windows Start Menu: right-click Cmder and choose **Add to Start**, then restart
168Codex or reboot.
