Surfaces: Desktop App, Cloud, IDE, and CLI

Lesson rewritten November 3, 2026 based on the Codex CLI, Codex IDE extension, Codex Cloud pages, and the Codex command reference. The previous version instructed users to install a non-existent npm package (@openai/codex-cli) and cited a --interactive flag that does not exist; options have been verified against CLI 0.166.0. Sources: Codex CLI · Codex IDE extension · Codex Cloud.

One Agent, Multiple Surfaces

Codex isn’t a single application; it’s an agent accessible through multiple surfaces, each tailored to a specific work context. The agent remains the same; what changes is where it works—your local machine or the cloud—the context it has access to, and how you track execution. Choosing the right surface often makes more difference in your daily workflow than choosing a specific model.

The ChatGPT Desktop App

The ChatGPT desktop app for macOS, Windows, and Linux is the most comprehensive entry point. Sign in with your ChatGPT account, open a folder or project, then select Codex from the ChatGPT menu for software development. The agent then works on the files in that folder using your local developer tools. This is the surface for long sessions and local projects. It’s also where you launch cloud-based work, just as you can from the web interface.

Codex Cloud

For tasks that need to run remotely, Codex Cloud executes work in an environment you set up once. On the web or in the desktop app, choose Work in › Cloud, then Select environment and Create environment. Select your GitHub repositories; Codex inspects the project, installs dependencies and tools, tests the workflow, and prompts you for any missing access permissions. Once the environment is published, every task gets its own workspace and continues running even when your computer sleeps. You review modified files and test results, request fixes, then commit or open a pull request—from the web, mobile, or desktop app.

This is the surface for long-running jobs you kick off before a meeting: a framework migration, extensive refactoring, or multiple parallel tasks on the same environment.

The IDE Extension

The Codex extension installs in Visual Studio Code and compatible editors like Cursor, Windsurf, and VS Code Insiders. Xcode and JetBrains IDEs offer their own native Codex integrations. Once connected, open Codex via its icon (or in VS Code and derivatives, via the Command Palette: Codex: Open Codex Sidebar; in JetBrains, open AI Chat and select Codex).

Its advantage is immediate context: open files, current selections, and recent conversations feed directly into your prompt, and changes appear side-by-side with your code. This is the surface for daily tasks—generating tests for the current function, explaining an inherited code block, or fixing an error the integrated terminal just displayed. When a task grows too large, you can delegate it to the cloud from the editor and return to the results later. Documentation recommends creating Git checkpoints before and after a task so you can roll back if needed.

The CLI

The CLI targets developers who live in the terminal. Documentation offers four installation methods:

# macOS and Linux: standalone installer
curl -fsSL https://chatgpt.com/codex/install.sh | sh

# npm
npm install -g @openai/codex

# Homebrew
brew install --cask codex

On Windows, run the standalone installer from PowerShell: powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex".

Running codex without arguments in a project folder opens the interactive terminal interface. On first launch, it prompts you to sign in with your ChatGPT account or another method.

# Open an interactive session
codex

# Open a session with an initial prompt
codex "Add email validation to the signup form"

# Select a model
codex --model gpt-6.1-sol "Refactor the payment module"

Its real value shines when you move beyond manual usage. codex exec (alias codex e) runs a task without interaction, making it ideal for scripts and pipelines. When stdin is redirected and a prompt is also provided, codex exec appends the received content to the prompt inside a <stdin> block. This lets you chain commands that produce file lists.

# Find files without tests and ask Codex to generate them
find src/ -name "*.ts" -not -name "*.test.ts" | codex exec "Generate missing tests for these files"

Which Surface Should You Choose?

In practice, most developers combine these surfaces within a single week. Login sessions are shared: the CLI and extension reuse the same cached credentials. And all surfaces read the same AGENTS.md file, the instruction file covered in the next lesson.

Key Takeaways

• Codex is accessible via the ChatGPT desktop app, Codex Cloud, the IDE extension, and the CLI
• The desktop app and extension work locally; Codex Cloud executes tasks in published environments
• The extension installs in VS Code and derivatives; Xcode and JetBrains have their own integrations
• Install the CLI via the standalone installer, npm install -g @openai/codex, or Homebrew; use codex exec for automation
• All surfaces read the same AGENTS.md file