The Four Surfaces | Understanding Codex

Codex is not a single application. It is an agent that runs across four distinct surfaces, each optimized for a different workflow. Understanding which surface to use -- and when to switch -- is one of the highest-leverage skills you can develop.

The Four Surfaces at a Glance

Surface	Best For	Key Trait
CLI	Terminal-native developers, scripting, CI/CD	Unix-composable, pipeable, automatable
Desktop App	Long-running sessions, multi-repo work	Persistent context, background tasks
IDE Extension	In-editor coding, visual diff review	Tight coupling with your editing workflow
Cloud (Codex Web)	Parallel tasks, team collaboration, PR creation	Async fire-and-forget, GitHub integration

1What is your task?

2Quick terminal command or script? --> CLI

3Multi-file changes + need to run commands? --> Desktop

4Editing code and want inline suggestions? --> IDE

5Fire-and-forget tasks or team collaboration? --> Cloud

The CLI: Power in the Terminal

The CLI is the foundation of Codex. Everything else is built on top of it.

Install it with npm (npm i -g @openai/codex) or Homebrew (brew install --cask codex). Once installed, you get two primary modes:

Interactive mode: codex -- launches a rich terminal UI (TUI) where you have a conversation with the agent. It reads your codebase, proposes changes, and runs commands with your approval.
Exec mode: codex "description" -- non-interactive, one-shot execution. Perfect for scripting, CI/CD pipelines, and automation.

The CLI is Unix-composable. You can pipe output into it:

Bash

# Feed error logs directly to Codex for diagnosis
npm test 2>&1 | codex "diagnose these test failures"

# Generate structured JSON output
codex --json "list all TODO comments in this repo"

The CLI is the Integration Layer

Every other surface ultimately relies on the same core engine as the CLI. If you understand the CLI deeply, you understand how Codex works at the fundamental level. The Desktop, IDE, and Cloud surfaces add convenience and UI -- but the CLI is where you learn the mechanics.

The Desktop App

The Desktop app wraps the CLI in a native application with a persistent session. Key advantages:

Persistent context: Your conversation history survives across sessions. The CLI starts fresh each time (unless you explicitly resume a thread).
Multi-repo support: Easily switch between projects without navigating terminal directories.
Background tasks: Long-running operations continue while you work on other things.
Visual diffs: See proposed changes in a graphical diff viewer rather than terminal patches.

The Desktop app is ideal for extended coding sessions where you are working on a complex feature over hours, not minutes. The persistent context means the agent remembers what you discussed earlier, what approaches you rejected, and what constraints you established.

The IDE Extension

Codex integrates with VS Code and JetBrains IDEs through extensions. The IDE surface is optimized for:

In-editor interaction: Ask questions about the code you are looking at without leaving your editor.
Inline suggestions: Get completion and refactoring suggestions that appear directly in your code.
Visual review: See proposed changes as inline diffs that you accept or reject per-hunk.

Before

CLI workflow: Read the agent's proposed changes as terminal output. Copy patches manually. Switch between terminal and editor to verify context. Best for developers who live in the terminal and prefer text-based interaction.

After

IDE workflow: See proposed changes as inline diffs in your editor. Accept or reject each change visually. Never leave your editor. Best for developers who prefer visual feedback and tight editor integration.

Cloud Codex

Cloud Codex runs in the browser at chatgpt.com. It connects to your GitHub repositories and runs tasks in containerized environments. This surface is fundamentally different from the others because it is asynchronous:

You describe a task ("Add input validation to all API routes")
Codex spins up a container with your repo cloned
The agent works autonomously -- reading code, making changes, running tests
When done, it creates a PR or presents the changes for review

Key properties of Cloud Codex:

GitHub-native: Connects directly to your repos. Creates branches and PRs.
Container isolation: Each task runs in its own container. No risk of one task corrupting another.
Internet access control: You configure whether the agent can access the internet, and if so, which domains. Default is no internet access for maximum safety.
Parallel tasks: Run multiple tasks simultaneously. Each gets its own container.

When Cloud Codex Shines

Choosing the Right Surface

The wrong surface will not prevent you from getting work done -- but it will slow you down. Here is how experienced Codex users think about the choice:

Match the surface to the workflow shape. Use CLI for quick terminal tasks and scripting. Use Desktop for extended sessions. Use IDE for in-editor coding. Use Cloud for async, parallel work.

Don't

Pick one surface and use it for everything. Each surface has genuine strengths. A developer who only uses the CLI is missing the async power of Cloud. A developer who only uses Cloud is missing the interactive debugging power of the CLI.

beginner

Surface Selection Practice:

List three tasks from your current sprint
For each task, choose the best Codex surface and write one sentence explaining why
Identify one task that would benefit from starting on one surface and switching to another mid-task
If you have access to Codex, try the same simple task (e.g., "explain this function") on two different surfaces and compare the experience

Concept Card