Codex CLI vs Codex app vs IDE extension: which surface to use

Codex CLI vs Codex app comes down to where you want the agent to live. The CLI runs in your terminal against the directory you start it in and scripts well with codex exec. The Codex app, which since July 9, 2026 is the Codex view inside the ChatGPT desktop app, adds parallel chats in Git worktrees, a diff pane with commit and pull request controls, and scheduled tasks. The IDE extension puts Codex beside your open files in VS Code, Cursor, Windsurf and JetBrains IDEs.

All three are clients for the same agent and read the same config.toml (openai/codex README, Best practices).

Applies to: Codex CLI 0.162.1 (released October 9, 2026) and OpenAI’s Codex documentation as of October 11, 2026. Last checked: October 11, 2026.

If you are new to Codex, start with What is Codex for install, sign-in and models. This page only covers how the three local surfaces differ and when to pick each.

On this page

The three surfaces at a glance

Sources: Codex CLI, Projects and chats, Codex environments, Codex IDE extension, IDE extension (OpenAI Developers), Authentication, Developer settings.

What happened to the Codex app

The Codex app merged into the ChatGPT desktop app. OpenAI’s changelog entry for July 9, 2026 says “Codex is now part of the ChatGPT desktop app on macOS and Windows” and that existing Codex app users can update as usual and keep their projects, settings and workflows; you can make Codex the default view and, on macOS, keep the Codex app icon (ChatGPT & Codex changelog). OpenAI’s help article adds that the previous ChatGPT desktop app may stay installed as ChatGPT Classic, and that desktop Codex chats can be reached from the Remote tab in the ChatGPT mobile app (Moving to the new ChatGPT desktop app).

So when people search for the “Codex app” today, they mean Codex inside the ChatGPT desktop app. The ChatGPT desktop app page offers downloads for macOS, Windows and Linux; after you sign in, you choose ChatGPT or Codex and start a Codex chat with New chat. The openai/codex README still says to run codex app if you want the desktop app experience:

codex app

When to use the Codex CLI

The Codex CLI page describes it as the way to “inspect code, make changes, run commands, and automate repeatable work without leaving your terminal.” Pick it when:

• You script Codex or run it in CI. codex exec runs without the interactive UI, streams progress to stderr and prints only the final message to stdout (Non-interactive mode):

  codex exec "summarize the repository structure and list the top 5 risky areas"
  

  Add --json for a JSON Lines event stream, or --output-schema for a final answer that fits a JSON Schema.

• You want a local review before you commit. /review runs against uncommitted changes, a commit or a base branch and reports findings without modifying your working tree (Codex CLI).

• You work over SSH or on a headless machine. The CLI supports codex login --device-auth (beta) when the browser callback can’t reach the machine (Authentication).

• You keep one focused loop per repository. The CLI treats the directory where you start it as the project and doesn’t show the ChatGPT Projects view (Projects and chats).

Other commands the CLI page lists: codex resume to reopen a saved chat, codex --image to attach a screenshot or diagram, codex --search for live web search, codex cloud to submit and apply cloud tasks from the terminal, codex mcp to add MCP servers, and codex completion for shell completions.

Install it with the standalone installer on macOS or Linux (the same command updates it), as the README shows:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

On Windows:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

Or with npm or Homebrew:

npm install -g @openai/codex
brew install --cask codex

When to use Codex in the ChatGPT desktop app

Pick the app when you run several pieces of work at once, want Git controls next to the chat, or need recurring jobs:

• Parallel chats without clashing. When you start a Codex chat you choose Local (your current project directory), Worktree (an isolated Git worktree) or Cloud (a remote task in a published environment). Local and Worktree both run on your computer (Codex environments).
• Worktrees and Handoff. Codex creates managed worktrees in $CODEX_HOME/worktrees in a detached HEAD state, and Hand off moves a chat between your local checkout and its worktree while Codex handles the Git steps. A .worktreeinclude file at the repository root lists ignored files, such as .env, to copy into new worktrees (Worktrees).
• Local environments. Setup scripts run when Codex creates a worktree, and actions (start the dev server, run the tests) appear in the top bar and run in the integrated terminal. The configuration lives in the .codex folder at the project root, so you can commit it. The docs say local environments are available only in Codex in the ChatGPT desktop app (Local environments).
• Git without leaving the chat. The diff pane lets you comment inline for Codex, stage or revert chunks or files, commit, push and create a pull request (Local environments).
• Scheduled tasks. From the Scheduled page you choose the project, prompt, cadence and whether the task runs in a dedicated worktree or your local environment (Best practices).
• Several folders in one project. A local project can attach multiple folders; the primary one is the default for Git operations and for discovering AGENTS.md, skills and config.toml (Projects and chats).

When to use the Codex IDE extension

Pick the extension when the work starts from the file in front of you. The IDE extension page says it lets you “bring open files and selections into the prompt, review edits in place, and hand off longer work.”

• Editors. VS Code, Cursor, Windsurf and VS Code Insiders use the Codex extension; Xcode and JetBrains IDEs provide their own integrations (in Xcode, choose Codex as the agent in the coding assistant; in JetBrains IDEs, open AI Chat and select Codex). If the Codex icon is missing in a VS Code-compatible editor, run Codex: Open Codex Sidebar from the Command Palette (Codex IDE extension).
• Platforms. OpenAI says the VS Code-compatible and JetBrains integrations work on macOS, Windows and Linux; on Windows you can run Codex natively with the Windows sandbox or use WSL2 (IDE extension). The chatgpt.runCodexInWindowsSubsystemForLinux setting runs it in WSL when available (Developer settings).
• Cloud follow-up from the editor. You can delegate a longer job to a cloud environment, follow its progress, then preview the changes and apply the diff locally (IDE extension).
• Approval modes. The extension switches between Chat, Agent and Agent (Full Access) (IDE extension).

Warning

OpenAI presents the three modes as a choice of “how much autonomy you want Codex to have”, and Agent (Full Access) is the most (IDE extension). For codex exec, OpenAI says to set the least permissions the workflow needs, such as --sandbox workspace-write to allow edits, and to “use danger-full-access only in a controlled environment (for example, an isolated CI runner or container)” (Non-interactive mode). The default permissions mode applies sandboxing automatically in the app, the CLI and the extension (Sandbox). See Codex: dangerously skip permissions and safer modes for the full list of flags.

What all three share

• Configuration. “The CLI, IDE extension, and ChatGPT desktop app all share the same configuration layers” (Best practices). Personal defaults live in ~/.codex/config.toml; a trusted project can add .codex/config.toml (Config basics).
• MCP servers. MCP configuration lives in config.toml, so a server added in the app’s settings also applies to the CLI and the IDE extension (Developer settings). From the CLI, codex mcp add adds one (Best practices).
• Skills and AGENTS.md. Skills work across the CLI, the IDE extension and the desktop app. AGENTS.md files layer from a global one in ~/.codex to more specific files closer to your working directory, and the closer file wins (Best practices).
• Sign-in. The desktop app, CLI and IDE extension each accept Sign in with ChatGPT or an API key for local work; Codex cloud requires ChatGPT sign-in. The CLI and the extension share the same cached login (Authentication).
• App and editor together. When the desktop app and the IDE extension are open in the same project, they share active chats and editor context. You can open an app chat from the extension and continue an IDE chat in the app (Developer settings).

One difference: the extension also has editor-only chatgpt.* keys (for example chatgpt.reviewDelivery or chatgpt.followUpQueueMode) that belong in the editor’s settings, not in config.toml (Developer settings). For hook configuration, see Codex hooks.

Which surfaces your plan includes

The Codex pricing page splits access by plan and sign-in:

Local messages and cloud chats share your plan’s usage allowance (Pricing). For the five-hour and weekly windows see Codex usage, and for per-plan details the Codex Plus and Codex Free listings.