How to Integrate Codex CLI with Your IDE

The Codex IDE extension brings OpenAI's coding agent directly into your editor. Whether you use VS Code, Cursor, or Windsurf, you can access Codex without leaving your development environment. This guide covers installation, configuration, and best practices for integrating Codex into your IDE workflow.

Prerequisites

Before setting up the IDE integration, ensure you have:

• Codex CLI installed - See How to Install OpenAI Codex CLI for setup instructions
• A ChatGPT subscription (Plus, Pro, Team, Edu, or Enterprise) OR an OpenAI API key
• VS Code, Cursor, or Windsurf installed on your system
• Node.js 22 or higher (required for CLI features)

VS Code Extension Installation

The Codex extension is available in the Visual Studio Code Marketplace.

Step 1: Install the Extension

1. Open VS Code
2. Press Cmd+Shift+X (macOS) or Ctrl+Shift+X (Windows/Linux) to open Extensions
3. Search for "Codex" or "OpenAI Codex"
4. Select Codex - OpenAI's coding agent published by OpenAI
5. Click Install
6. Reload VS Code when prompted

Step 2: Sign In

After installation, the Codex icon appears in the Activity Bar:

1. Click the Codex icon in the sidebar
2. Click Sign in with ChatGPT in the Codex panel
3. Complete authentication in your browser
4. Return to VS Code - the extension activates automatically

Alternatively, use an API key:

1. Open VS Code Settings (Cmd+, or Ctrl+,)
2. Search for Codex API Key
3. Enter your OpenAI API key
4. Reload the extension

Step 3: Verify Installation

After signing in:

1. Open any project folder
2. Click the Codex icon in the sidebar
3. Type a prompt like "What files are in this project?"
4. Verify Codex responds with project information

Cursor IDE Integration

Cursor is a VS Code fork with built-in AI features. The Codex extension works alongside Cursor's native AI capabilities.

Installing in Cursor

1. Open Cursor
2. Press Cmd+Shift+X (macOS) or Ctrl+Shift+X (Windows/Linux)
3. Search for "OpenAI Codex"
4. Install the extension
5. Reload Cursor

Positioning the Codex Panel

Cursor's layout may hide the Codex icon. To make it visible:

1. Look for Codex in the collapsed section of the Activity Bar
2. Drag the Codex icon to your preferred position (such as the right sidebar)
3. If the Activity Bar is horizontal, temporarily switch to vertical layout:
   • Open Settings
   • Search for Activity Bar Orientation
   • Set to Vertical
   • Move the Codex icon
   • Revert to your preferred orientation

Using Codex Alongside Cursor AI

You can use both Codex and Cursor's native AI features:

• Cursor AI: Quick inline completions and chat
• Codex: Agent-based tasks with file system access and command execution

Both tools complement each other for different use cases.

Windsurf Integration

Windsurf is another VS Code-compatible editor with AI enhancements. The Codex extension installs similarly.

Installing in Windsurf

1. Open Windsurf
2. Access the Extensions view
3. Search for "OpenAI Codex"
4. Install and reload

Windsurf-Specific Features

Windsurf provides interactive debugging support that complements Codex:

• When builds fail, Windsurf can auto-suggest sending console errors to Codex
• Codex analyzes errors and suggests fixes
• Changes apply automatically with your approval

This tight feedback loop speeds up debugging workflows.

Extension Modes

The Codex IDE extension offers three operating modes:

Chat Mode

A safe mode for planning and discussion:

• Codex cannot read files or run commands
• Ideal for brainstorming and asking questions
• No project modifications possible

Agent Mode (Default)

Balanced mode for everyday development:

• Codex can read files and write code
• Requires approval before executing commands
• Recommended for most development tasks

Agent (Full Access) Mode

Autonomous mode for larger tasks:

• Codex operates without asking permission
• Runs commands and edits automatically
• Use only in sandboxed environments or experimental branches

To change modes, click the mode selector in the Codex panel.

Terminal Workflows Within IDEs

You can use the Codex CLI directly in your IDE's integrated terminal.

Opening the Integrated Terminal

• VS Code: Ctrl+` or Cmd+ `` (macOS)
• Cursor: Same as VS Code
• Windsurf: Same as VS Code

Running Codex in Terminal

# Start an interactive session
codex

# Run a single command
codex "add error handling to the selected function"

# Review changes before committing
codex review

Terminal vs Extension

Use the terminal for complex shell operations and the extension for contextual code assistance.

Configuration

Both the CLI and IDE extension share ~/.codex/config.toml.

Essential Settings

# Model selection
model = "gpt-5-codex"

# Approval behavior
approval_policy = "on-request"  # untrusted, on-failure, on-request, never

# Sandbox mode
sandbox_mode = "workspace-write"  # read-only, workspace-write

# Network access for sandbox
[sandbox_workspace_write]
network_access = true

IDE-Specific Settings

Configure VS Code settings for Codex behavior:

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true,
  "codex.defaultMode": "agent"
}

Project-Level Configuration

Create a AGENTS.md file in your project root to provide Codex with project-specific guidance:

# Project Instructions for Codex

## Build Commands
- `npm run build` - Build the project
- `npm test` - Run tests

## Conventions
- Use TypeScript for all new files
- Follow existing code style
- Add tests for new features

## Deployment
- Do not modify production configuration files
- All changes require code review

Codex reads this file and follows your project's conventions.

Cloud vs Local Tasks

The IDE extension supports both local and cloud-based execution.

Local Execution

• Uses your local machine's file system
• Requires a project folder open in the editor
• Full access to local tools and dependencies

Cloud Execution

• Runs in OpenAI's sandboxed cloud environment
• Can branch from main or your local changes
• Track progress without keeping your machine running

To start a cloud task:

1. Open the Codex panel
2. Click Run in cloud
3. Choose whether to run from main or local changes
4. Monitor progress in the panel

Platform-Specific Setup

macOS

The Codex IDE extension works natively on macOS with full features:

# Install via Homebrew (recommended)
brew install codex

# Or via npm
npm install -g @openai/codex

macOS uses Seatbelt for sandboxing, providing secure command execution.

Linux

Linux installation follows the same process:

# Install via npm
npm install -g @openai/codex

# Or download the binary
curl -LO https://github.com/openai/codex/releases/latest/download/codex-x86_64-linux.tar.gz
tar -xzf codex-x86_64-linux.tar.gz
sudo mv codex /usr/local/bin/

Linux uses Landlock for sandbox security.

Windows

Windows support is available but WSL is recommended for the best experience.

Native Windows Setup:

1. Install Node.js 22 or higher
2. Open PowerShell:

npm install -g @openai/codex

3. The extension works in VS Code but with experimental sandbox support

WSL Setup (Recommended):

1. Install WSL:

wsl --install

2. Open your WSL terminal and install Node.js:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
source ~/.bashrc
nvm install 22

3. Install Codex:

npm install -g @openai/codex

4. Configure VS Code to use WSL:

{
  "chatgpt.runCodexInWindowsSubsystemForLinux": true
}

WSL Performance Tip: Store repositories in your Linux home directory (~/projects/) rather than Windows paths (/mnt/c/Users/...) for significantly better performance.

Best Practices

Use Git Before Major Changes

Codex can modify your codebase significantly. Create checkpoints:

git add -A
git commit -m "Checkpoint before Codex task"

Leverage File Context

The IDE extension automatically uses context from:

• Currently open files
• Selected code
• Referenced files using @filename in prompts

This enables shorter, more precise prompts.

Set Appropriate Approval Levels

• Development: Use Agent mode with approvals
• Code review: Use Chat or Read-only mode
• Automated tasks: Use Full Access only in isolated environments

Combine with Code Review

After Codex makes changes, use the /review command:

/review

This runs a separate review agent to catch issues before committing.

Troubleshooting

Extension Not Appearing

If the Codex icon does not appear after installation:

1. Reload VS Code (Cmd+Shift+P > "Reload Window")
2. Check the Extensions panel for Codex status
3. Verify the extension is enabled for your workspace

Sign-In Loop

If authentication keeps prompting:

1. Sign out: codex auth logout in terminal
2. Clear VS Code authentication cache
3. Restart VS Code
4. Sign in again

Proxy or Firewall Issues

If Codex cannot connect:

1. Configure VS Code proxy settings:

{
  "http.proxy": "http://proxy.example.com:8080"
}

2. Ensure outbound HTTPS (port 443) is allowed

Windows Performance Issues

If Codex runs slowly on Windows:

1. Use WSL instead of native Windows
2. Store projects in Linux filesystem, not /mnt/c/
3. Verify Node.js 22+ is installed in WSL

Extension Conflicts

If Codex conflicts with other AI extensions:

1. Disable conflicting extensions temporarily
2. Check for keyboard shortcut conflicts in Settings > Keyboard Shortcuts
3. Use the Codex panel instead of shortcuts if conflicts persist

Next Steps

• Learn how to use Codex for code review with the /review command
• Explore Codex configuration options for advanced customization
• Read about orchestrating multiple AI tools for efficient development workflows
• Check out the official Codex IDE documentation for the latest features