Install Codex and set up your first project

1. Choose your installation path

Use the desktop app if you want a visible project list, file previews, and a review panel. Use the CLI if you already work in a terminal. You do not need to install both to complete this guide.

OpenAI's former Codex app documentation now leads to the ChatGPT desktop app documentation, which includes Codex. If the downloaded app or documentation uses that name, choose Codex in the app. Older screenshots may still show the standalone Codex branding.

Reference: OpenAI: Desktop app

2. Install the desktop app on Mac or Windows

On macOS, use the current ChatGPT download page, which selects the appropriate installer for Apple Silicon or Intel. The documented minimum is macOS 14, with an M1-or-newer Apple Silicon chip or an Intel processor. Install the new desktop app for Codex; ChatGPT Classic is the older app.

On Windows, follow the Microsoft Store link on OpenAI's Windows desktop page. Install and open the app, sign in with your ChatGPT account, then choose Codex and open your project folder. Complete the native sandbox setup if prompted. WSL is optional for a native Windows project.

The current Windows sandbox guidance recommends Windows 11 and describes recent Windows 10 as best effort. Keep the first project in a normal local folder you can identify. Avoid starting at your entire home directory or a directory containing unrelated private files.

Reference: OpenAI: Download the macOS app · OpenAI: Windows desktop app · OpenAI: Windows sandbox

3. Or install Codex CLI

If Node.js and npm are already installed, the npm command below installs the official CLI. Open a new terminal afterward if the command is not found. macOS users with Homebrew can alternatively use 'brew install --cask codex'. Choose one installation method so updates remain easy to understand.

On Windows, use a native terminal such as PowerShell for a Windows project. If npm.ps1 is blocked by shell policy, use the installed npm.cmd shim for the same command rather than changing system-wide policy. If you do not have a package manager, use the platform installer listed in the official CLI instructions.

npm install -g @openai/codex
codex --version

Reference: OpenAI: Codex CLI

4. Open the project and initialize instructions

In the app, open the folder you intend to work on and start a Codex task there. In the CLI, change into that folder and run codex. On first launch, follow the offered sign-in flow. You do not need to create an API key just to try the ChatGPT sign-in route; account access is subject to your plan and workspace settings.

Begin with 'Explain this project and identify its setup and test commands. Do not edit files.' Confirm that the response names the correct project. For an empty practice folder, ask Codex to propose a small project first; do not expect it to discover tests that do not exist.

In the interactive CLI, /init can create an AGENTS.md starting point. Read an existing AGENTS.md before generating another, and review generated instructions for accuracy. In the desktop app, you can ask Codex to draft the same file in ordinary language. This is project guidance, not a prerequisite for signing in or a substitute for git init.

cd path/to/your-project
codex

Reference: OpenAI: Codex CLI · OpenAI: Developer commands · OpenAI: AGENTS.md · OpenAI: Authentication

5. Make one change you can check

Choose a small visible task, such as correcting a heading or adding an empty-state message. Describe the expected result and ask Codex to preserve unrelated work. Review the changed files, run the relevant existing check, and inspect the result.

For a new local practice folder, Git can provide a checkpoint before you make larger changes. Follow your repository's existing process if it already has Git. Installation is complete when Codex can inspect the intended files and you understand what it is allowed to change; a complex automation setup can wait.

Try it in Codex

Initialize with a read-only first task

I am getting started with Codex in this project. Inspect the current directory and existing README and AGENTS.md files. Do not edit anything yet.

Tell me what the project does, which files are the main entry points, which setup and test commands actually exist, and whether this directory is a Git repository. If the folder is empty, say so and suggest a small practice project.

Explain the active permission limits if available. Suggest one small first task and how I can verify it. If project instructions are missing, propose concise AGENTS.md content for my review. Do not install dependencies, create accounts, commit, push, or deploy.

Check your result

• The app opens, or codex --version reports the installed CLI.
• Sign-in succeeds and Codex identifies the intended project directory.
• Existing project instructions are preserved; any new AGENTS.md is reviewed.
• You can explain what your first task will change and how to check it.

Sources and scope

Official references support the product behavior described above. The task prompts and practical checks are our community guidance.

• OpenAI: Desktop appCurrent desktop download, naming, sign-in, and selecting Codex.
• OpenAI: Windows desktop appMicrosoft Store distribution and native Windows setup.
• OpenAI: Windows sandboxNative sandbox availability and Windows version guidance.
• OpenAI: Codex CLIOfficial npm, Homebrew, and standalone installation routes; starting a local session.
• OpenAI: Developer commandsThe interactive CLI /init command; it does not initialize a Git repository.
• OpenAI: AGENTS.mdHow project instructions are discovered and applied.
• OpenAI: Download the macOS appmacOS 14, Apple Silicon and Intel support, installer selection, and the distinction from ChatGPT Classic.
• OpenAI: AuthenticationAvailable sign-in methods and account access boundaries.

Something changed in your version? Send a correction with the guide URL, platform, and version. Leave out credentials and private project content.