Installation

You signed up for ChatGPT Plus, you have heard that Codex can write code across four different surfaces, and now you are staring at the downloads page wondering which one to install first. The answer: all three local surfaces take under 5 minutes combined, and they share the same authentication and configuration once set up.

What You’ll Walk Away With

• The Codex App installed on macOS (Apple Silicon)
• The Codex CLI available globally via codex command
• The Codex IDE extension running in VS Code, Cursor, or Windsurf
• All three surfaces sharing the same ~/.codex/ configuration directory
• Verification that each surface launches and authenticates correctly

Install the Codex App (macOS)

The Codex App is a native macOS application for Apple Silicon Macs. It provides the richest experience: parallel threads, worktree isolation, built-in Git tools, automations, and an integrated terminal.

1. Download the DMG from persistent.oaistatic.com/codex-app-prod/Codex.dmg.

2. Open the DMG and drag Codex to your Applications folder.

3. Launch Codex from Applications. macOS may ask you to confirm opening an app from an identified developer — click Open.

4. Sign in with your ChatGPT account or OpenAI API key when prompted.

5. Select a project folder. Codex will remember this project for future sessions.

Caution

The Codex App is currently macOS-only (Apple Silicon). Windows and Linux support is coming — you can sign up for notifications to get notified when it ships.

Tip

Prompt to verify the App is working:

After selecting a project, type this into the Codex App thread:

Tell me about this project

Codex should read your project structure and give you a summary. If it does, the App is fully operational.

Install the Codex CLI

The CLI is open-source, built in Rust, and runs on macOS, Linux, and Windows. Choose your preferred package manager.

npm

npm install -g @openai/codex

Verify the installation:

codex --version

Upgrade to the latest version later with:

npm install -g @openai/codex@latest

Homebrew

brew install codex

Verify the installation:

codex --version

Upgrade later with:

brew upgrade codex

After installing, run codex in a terminal. The first time you launch it, you will be prompted to sign in with your ChatGPT account or API key.

Note

The CLI is available on macOS, Linux, and Windows. For the best Windows experience, run Codex inside a WSL workspace and follow the Windows setup guide.

Tip

Prompt to verify the CLI is working:

Navigate to a project directory and run:

codex "What files are in this project?"

If Codex lists your files, authentication and sandboxing are both working.

Install the IDE Extension

The Codex IDE extension works with VS Code, Cursor, Windsurf, and JetBrains IDEs.

VS Code

Install from the Visual Studio Code Marketplace or open VS Code and search for “Codex” in the Extensions panel.

After installation, the Codex icon appears in your left sidebar. Click it, sign in, and you are ready.

Cursor

Install the extension by searching for “Codex” in Cursor’s extension panel or use cursor:extension/openai.chatgpt.

The activity bar in Cursor displays horizontally by default, which can hide the Codex icon. If you do not see it, look for collapsed items or pin the Codex extension in the bar.

Windsurf

Search for “Codex” in Windsurf’s extension panel or use windsurf:extension/openai.chatgpt.

JetBrains

For IntelliJ, PyCharm, WebStorm, Rider, and other JetBrains IDEs, install the JetBrains Codex integration from the JetBrains plugin page. It supports ChatGPT login, API keys, and JetBrains AI subscriptions.

Moving Codex to the Right Sidebar

Most developers prefer the Codex panel on the right side of their editor, keeping the file explorer on the left.

In VS Code, simply drag the Codex icon from the left sidebar to the right. In Cursor, you may need to temporarily set the activity bar orientation to vertical in Workbench settings, restart, drag the icon, then reset to horizontal.

Tip

Prompt to verify the IDE extension is working:

Open the Codex sidebar panel and type:

Tell me about this project

Codex should read your open workspace and summarize it.

How the Surfaces Connect

All three local surfaces (App, CLI, IDE Extension) share the same configuration and credentials:

Shared resource	Location
User config	~/.codex/config.toml
Authentication	~/.codex/auth.json or OS keyring
MCP servers	Defined in config.toml, shared by all surfaces
AGENTS.md	Read from ~/.codex/AGENTS.md (global) and project root (project-level)

This means you only configure once. Set your approval policy in config.toml, and the App, CLI, and IDE extension all respect it. Add an MCP server via codex mcp add, and it appears in all three surfaces.

The Codex App and IDE extension also sync when both are open in the same project. The App tracks which files you view in your editor (Auto Context), and threads started in one surface appear in the other.

When This Breaks

App does not open on macOS: Ensure you are on Apple Silicon (M1 or later). Intel Macs are not supported. Check System Settings > Privacy & Security if macOS blocks the app.

CLI install fails with npm: Make sure Node.js 18+ is installed (node --version). If you get EACCES errors, do not use sudo — instead run npm config set prefix ~/.npm-global and add ~/.npm-global/bin to your PATH.

IDE extension not visible: In Cursor, the extension may be hidden in the collapsed section of the horizontal activity bar. Look for a >> overflow menu in the bar, or switch to vertical orientation temporarily.

Authentication does not persist: Check that ~/.codex/auth.json exists after signing in. If it is missing, your OS credential store may be in use. See the authentication guide for credential storage configuration.

“codex: command not found” after Homebrew install: Run brew link codex or ensure /opt/homebrew/bin is in your PATH.

What’s Next

Set Up Authentication Configure ChatGPT subscription access or API key billing