Last updated

Codex App vs Codex CLI: Differences, When to Use Each, and Alternatives

The Codex app now lives inside the ChatGPT desktop app. The CLI is still the open-source, scriptable way to run Codex anywhere. Neither runs other vendors' agents.

16 min read

The Codex app is now Codex inside the ChatGPT desktop app: OpenAI merged the two on July 9, 2026. Choose the desktop app when you want parallel chats with managed Git worktrees, a Handoff button that moves work between your checkout and a worktree, a diff pane with Git controls, and cloud tasks in one window on macOS, Windows, or Linux (in preview). Choose the Codex CLI when you work in a terminal, script Codex with codex exec, run it in CI or on a remote machine, or want the open-source client; since October 2026 it manages worktrees too. You can also use both: they run on the same ChatGPT account and share MCP configuration. Neither runs Claude Code or any other vendor's agent, so if you want Codex beside them, you need a third tool.

This explainer covers every official Codex surface (the desktop app, the CLI, the IDE extension, Codex Cloud, and Codex on mobile), what Local, Worktree, and Cloud mean, notifications, and where a multi-agent workspace fits when Codex is one of several agents, with a task we ran through Codex and Claude Code side by side. We first published it on October 5, 2026, and re-checked every Codex claim against OpenAI's documentation and release notes on November 14, 2026. Agentastic publishes this explainer and makes one of the alternatives it discusses.

What happened to the Codex app?#

Short version: the Codex app is now part of ChatGPT. If you searched for "Codex app" and landed on a page about ChatGPT, nothing is broken; OpenAI's What's new log tells the story:

  • February 2026: the Codex app launched on macOS as a desktop workspace for parallel project chats, Git review, worktrees, skills, and scheduled tasks.
  • March 2026: it arrived on Windows with native PowerShell and sandbox support.
  • July 9, 2026: the Codex app merged into the ChatGPT desktop app for macOS and Windows. Codex keeps its own coding experience next to ChatGPT's Chat and Work modes, and you can make Codex the default view.
  • August 2026: the ChatGPT desktop app, Codex included, reached Linux as a preview. The same August 11 release added import of instructions, settings, skills, plugins, projects, and recent work from Claude Code, Claude Cowork, or Cursor; the CLI got a matching /import command.

In practice, open the ChatGPT desktop app, choose Codex, and start a new chat. The capabilities people mean by "the Codex app" (worktrees, handoff, the diff pane, scheduled tasks, skills, and plugins) all live there now. The documentation moved too: developers.openai.com/codex now redirects to learn.chatgpt.com, and the old Codex app page redirects to the desktop app guide. The rest of this article says "desktop app" for that surface.

The short answer#

SurfaceBest forPlatformsRuns onMain tradeoff
Codex in the ChatGPT desktop appParallel chats, worktrees, visual review, cloud tasks in one windowmacOS, Windows, Linux previewYour computer, an SSH host, or Codex CloudLess scriptable; one vendor's agent
Codex CLITerminal work, scripting, CI, remote boxesmacOS, Linux, WindowsWherever you run itNo GUI diff review, Handoff, or local environment scripts
IDE extensionFocused edits with editor contextVS Code, Cursor, WindsurfYour computer, or Cloud by delegationNo plugins or local environment setup scripts
Codex CloudLong tasks that should finish while you are awayWeb, mobile, desktop appOpenAI's cloud, from a published environmentCannot see local files, processes, or VPN
Codex on mobileStarting, approving, and reviewing from your phoneChatGPT iOS app with a connected Mac or Windows PCYour connected computerHost must stay awake, online, and signed in

Feature-by-feature comparison#

FeatureDesktop appCLIIDE extensionCloud
Parallel workParallel chats across projectsOne session per terminalChats beside your code; /fork, /sideEach task gets its own workspace
Git worktreesBuilt in: managed worktrees and HandoffManaged worktrees: --worktree, /worktree; no longer experimental since v0.164.0/worktree slash commandNot needed; separate working files per task
Local or cloudWork in This computer or Cloudcodex cloud, codex apply/local, /cloud—
Setup scripts and actionsLocal environments stored in .codexYour own scripts—Published cloud environments
Reviewing changesDiff pane with inline comments, stage, commit, push, PRReview mode for uncommitted changes, a commit, or a branchInline diffs; keep only the edits you wantReview results, then commit or open a PR
MCP serversYes, shared configurationYes, codex mcpYes, shared configuration—
SkillsYesYesYes—
PluginsPlugins tab/pluginsNot supported—
HooksYes, including plugin-bundled hooksYes; review with /hooksYes, same config layers as the CLI—
PermissionsAsk for approval, Approve for me, Full access/permissions, --sandbox, --ask-for-approvalSame control below the composerNetwork and secrets set per environment
AutomationScheduled tasks, including background worktreescodex exec, Codex SDK—codex cloud exec from the terminal
Remote accessHost for Codex on mobile; SSH host projects; Handoff between hostscodex remote-control (experimental); --remote to an app server—Web, mobile, and desktop
NotificationsTurn-complete, permission, and question alerts; Activity viewtui.notifications (OSC 9, OSC 777, or bell) and a notify programNo separate controls; notify on the connected hostWeb notification settings
Import from Claude Code or CursorSettings → Import, with automatic updates/import——
Runs other vendors' agentsNoNoNoNo
Open sourceNot listed by OpenAIYes, Apache-2.0NoNo

OpenAI's MCP guide confirms that the desktop app, CLI, and IDE extension share MCP server configuration through config.toml, so a server you add once is available in all three. The plugins page is equally clear that the IDE extension does not support plugins. The open-source page lists the CLI, SDK, and app server as open source and marks the IDE extension and Codex Cloud as closed.

Local, Worktree, and Cloud: what each mode means#

Every Codex chat in the desktop app starts with a choice of where it runs. OpenAI's environments guide puts Local and Worktree on your computer and Cloud on a published environment.

ModeWhere it runsIsolationGood forWatch out for
LocalYour project directoryNone; Codex edits your checkoutHands-on work, your usual dev server and IDETwo chats in one checkout can collide
WorktreeA separate Git worktree on your computerSeparate files, shared Git historyBackground tasks while you keep workingIgnored files need .worktreeinclude
CloudA published cloud environmentIts own workspace per taskLong tasks, work while your laptop sleepsNo access to local files, processes, browser sign-ins, or VPN

Local: the foreground#

Local means Codex works directly in the repository you opened. That is the right mode when you want to watch the change, run your existing dev server, or test in the environment you use every day. It is also the mode where parallel chats can step on each other, because they share one set of files.

Worktree: the background#

Worktree mode creates a Git worktree, a second checkout that shares the repository's history, so a chat can work without touching your files. According to the worktrees guide:

  • Codex creates managed worktrees under $CODEX_HOME/worktrees in a detached HEAD state, so several can exist without creating branches. Create branch here turns one into a branch when you want to push it.
  • Handoff moves a chat and its code between Local and its worktree. Codex handles the Git steps, because Git allows a branch to be checked out in only one place at a time.
  • Files ignored by Git do not travel with a handoff. List the ones a new worktree needs, such as .env, in a .worktreeinclude file.
  • Permanent worktrees created in earlier versions stay available, but the guide now says you can no longer create new ones from the project menu.
  • By default Codex keeps your 15 most recent managed worktrees, a limit you can change or turn off. It saves a snapshot before deleting one, so you can restore the chat's work later.

Pair worktrees with a local environment: a setup script that runs whenever Codex creates a worktree (installing dependencies, for example) and actions such as "Run" or "Test" that appear in the app's top bar. The configuration lives in a .codex folder you can commit, and local environments are a desktop-app feature.

Cloud: when your computer should be off#

Codex Cloud runs tasks in a cloud environment you prepare and publish from your GitHub repositories. Each task has its own working files and keeps going while your computer sleeps. You can start and follow tasks on the web, on mobile, or in the desktop app, and from a terminal:

bash
codex cloud # browse and submit cloud tasks codex apply <task-id> # apply a cloud task's latest diff locally

The catch is that a cloud task sees only what its environment provides. Your local files, running processes, browser sign-ins, and VPN do not transfer, so services the task needs must be configured in the environment's network and secret settings.

When the desktop app is the better choice#

  • You run several tasks at once. Worktree chats, Handoff, and automatic cleanup do the Git bookkeeping that is tedious by hand.
  • You review visually. The diff pane lets you comment inline, stage or revert individual chunks, commit, push, and open a pull request without leaving the chat.
  • Each worktree needs setup. Local environments run your install script on every new worktree.
  • You want work to happen on a schedule. Scheduled tasks can run in dedicated background worktrees so they don't collide with what you are doing.
  • You want to steer from your phone. Codex on mobile lets the ChatGPT iOS app start, approve, and review tasks on a connected Mac or Windows PC. You set it up in the desktop app under Settings → Connections → Control this Mac or PC.
  • The project lives on another machine. Per OpenAI's remote connections guide, the desktop app can open projects on an SSH host from your ~/.ssh/config, as long as codex is installed and signed in on that host. Handoff can move a chat and its Git state between your computer and the host, creating or reusing a worktree there.
  • You are moving from Claude Code or Cursor. Settings → Import brings over instructions, settings, skills, plugins, projects, and recent work, and can keep them in sync.

When the CLI is the better choice#

  • You live in the terminal. The Codex CLI keeps the loop in one place: explore, edit, run your tools, steer the active turn, and resume with codex resume.
  • You automate. codex exec runs Codex non-interactively for scripts and CI, with JSON Lines output when you need machine-readable events.
  • The machine has no desktop. Build servers, containers, and remote dev boxes only need a shell, and codex login --device-auth (in beta) signs in without a local browser, per OpenAI's authentication guide. Our guide to running agents over SSH covers keeping sessions alive and reviewing their work.
  • You want to audit or pin the client. The CLI is open source under Apache-2.0 in the openai/codex repository.
  • You automate with an API key. API-key sign-in covers the CLI, the SDK, and the IDE extension, which suits shared CI environments.
  • You want alerts your way. tui.notifications sends OSC 9, OSC 777, or a bell to your terminal, and a notify program can post completed turns anywhere. Our Claude Code and Codex notifications guide shows what each one fires on, from our own tests.

Installing takes one command on each platform:

bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh # macOS and Linux npm install -g @openai/codex # any platform with Node.js brew install --cask codex # Homebrew

On Windows, OpenAI provides a PowerShell installer. If you want the GUI later, codex app launches the desktop app on macOS or Windows, or starts its installer when it is missing.

Isolation used to be the CLI's main gap, and it mostly closed this fall. Managed worktrees arrived as an experiment in v0.154.0 (September 9, 2026), and v0.164.0 (October 23, 2026) retired the feature flag. The command reference now documents codex exec --worktree, codex fork <SESSION_ID> --worktree, and /worktree for browsing them. As of November 14, the newest stable CLI was v0.169.0, released November 13.

What the CLI still lacks is the bookkeeping around the worktree. In our test with CLI 0.167.2, codex exec --worktree worked in ~/.codex/worktrees/<id>/<repo> on a detached HEAD and left its changes uncommitted, so we had to create a branch and commit before merging. It also refuses to combine --worktree with --ignore-user-config. There is no Handoff and no local environment setup script, so dependencies are yours to install. Our guide to running Codex agents in parallel shows a manual git worktree add setup, and the git worktree docs explain the model.

Where the IDE extension fits#

The Codex IDE extension runs in VS Code, VS Code Insiders, Cursor, and Windsurf; Xcode and JetBrains IDEs offer Codex through their own integrations. It is the best surface for focused edits, because open files and selections become context automatically and diffs appear beside the code. Slash commands cover the essentials: /local, /worktree, and /cloud choose where a chat runs, and /side starts a temporary side chat. It shares configuration layers with the CLI, but it does not support plugins, so install those through the desktop app or the CLI.

Windows, Linux, and macOS#

  • macOS: the desktop app and the CLI are both available.
  • Windows: the desktop app for Windows runs Codex natively in PowerShell with a Windows sandbox, or in WSL2 when you prefer a Linux toolchain. It supports worktrees, scheduled tasks, Git, the built-in browser, plugins, and skills. The CLI installs from PowerShell.
  • Linux: the desktop app for Linux is a preview for Ubuntu 24.04 and 26.04, Debian 13, Fedora 43 and 44, and Arch Linux, on x64 and ARM64. Computer Use is not available there yet, and native Wayland support is experimental. The CLI has no such limits.

Pricing and sign-in#

Codex is included in every ChatGPT plan, from Free and Go through Plus, Pro, Business, Edu, and Enterprise, and ChatGPT Work shares the same usage limits. As of November 14, 2026, OpenAI's pricing page lists Go at $8 a month, Plus at $20, Pro at $100, $200, or $500, and Business at $20 per user per month billed annually ($25 monthly). The Free and Go cards list GPT-6 Luna at Standard speed in the desktop app, subject to rollout, while the Plus card is the first to list Codex on the web, in the CLI, in the IDE extension, and on iOS, plus cloud integrations such as automatic code review. Limits and model access vary by plan, so check the page before you commit to a workflow.

API keys are the other route. OpenAI's authentication guide lists API-key sign-in for the desktop app, the CLI, and the IDE extension at standard API rates, while the pricing page's API-key column names the CLI, SDK, and IDE extension. Either way, cloud features such as Codex Cloud, GitHub code review, and Slack need a ChatGPT plan.

Can the Codex app run Claude Code or other agents?#

No. Every surface in this article runs one agent: OpenAI's Codex. Two features can make it look otherwise, so it helps to be precise about what they do:

  • Model providers change the model, not the agent. The advanced configuration guide lets Codex call local models through Ollama or LM Studio, Amazon Bedrock, Google Cloud Vertex AI, Azure, or a custom endpoint. The harness, tools, and approvals are still Codex's.
  • Import copies setup, not sessions. Import brings Claude Code or Cursor instructions, skills, and recent work into Codex. It doesn't run Claude Code.

So if you want Claude Code to attempt the same task, a different vendor's CLI to review Codex's diff, or one place to watch all of them, you need a tool that runs each vendor's own CLI.

A demonstrated task: one bug, Codex and Claude Code#

To show what a second agent adds, we gave the same small bug to both on November 14, 2026. The repository had a slugify() function and three tests, two of them failing on punctuation and repeated separators. Both agents got the same prompt: "Make the failing tests in test_slug.py pass without editing the tests. Run python3 -m unittest to check."

bash
# Codex CLI 0.167.2, in a managed worktree it creates itself codex exec --worktree -s workspace-write -m gpt-6.1-sol \ -c model_reasoning_effort="low" "$PROMPT" # Claude Code 2.1.325, in a worktree we made by hand, on its default model git worktree add -b claude/fix-slugify ../slugs-claude && cd ../slugs-claude claude -p "$PROMPT" --permission-mode acceptEdits \ --allowedTools "Bash(python3 -m unittest*)"
  • Codex finished in 23 seconds and 4,035 tokens, in a fresh worktree under ~/.codex/worktrees/, with the change left uncommitted. We also passed -c overrides that turned off our own hooks, plugins, and MCP servers.
  • Claude Code finished in 15 seconds, with the change left uncommitted on its branch.

Both made all three tests pass, with different code. Codex removed characters that aren't word characters, spaces, or hyphens, then collapsed separators; Claude Code replaced every run of characters outside a-z0-9 with a hyphen. On inputs the tests never covered, they disagree:

InputCodex's slugClaude Code's slug
Café Crèmecafé-crèmecaf-cr-me
snake_case_namesnake_case_namesnake-case-name
C++ & Rustc-rustc-rust

Claude Code's summary flagged the accented-letter behavior on its own; Codex's did not mention it. Neither answer is wrong. They are two readings of a requirement the tests left open, and seeing both is what made the question visible. We committed Codex's change on a branch (git switch -c codex/fix-slugify), fast-forwarded main to it, re-ran the tests, and removed both worktrees. With one agent, we would have merged whichever reading came back first.

Codex app alternatives#

Which alternative fits depends on what the ChatGPT desktop app is missing for you:

If you wantConsiderWhat to know
Codex with an official GUIThe ChatGPT desktop appCodex only; macOS, Windows, and a Linux preview
Codex in a terminal, CI, or on serversThe Codex CLIOpen source; managed worktrees; no GUI review
Claude instead of Codex, in a desktop appThe Claude Code desktop appClaude only; local, SSH, and cloud sessions
Codex beside Claude Code and other CLI agents, with a worktree per taskA multi-agent workspace such as Agentastic or ParadevRuns each vendor's own CLI with your own sign-ins

Paradev, formerly Superset, describes itself on that page (updated November 5, 2026) as running any CLI agent on macOS, with an experimental Linux build and no Windows version, and says it never proxies model calls. Our roundup of Codex GUIs compares more options.

When one provider is not enough#

Every coding surface OpenAI ships is built around Codex. That is the right default if Codex is your only agent. It stops fitting when you want Claude Code to attempt the same task, a dedicated review CLI to check the result, or a container boundary that a worktree cannot give you.

Agentastic is a native macOS workspace that runs the real Codex CLI with your own OpenAI sign-in; it does not resell usage. Around the CLI it adds:

  • Mixed providers. Codex next to Claude Code, Gemini, Cursor, and the rest of more than 50 built-in agent definitions, plus any terminal command as a custom agent. To repeat the comparison above, check both Codex and Claude Code in Agent Home before you launch the prompt; each gets its own worktree and branch.
  • A worktree per task, with setup. Every agent, not only Codex, gets a git worktree, and a setup script in .agentastic/setup.sh prepares each one.
  • Stronger isolation and remote execution. Docker or Apple containers, SSH machines where sessions keep running after you close the Mac, and cloud agents on your own cloud account, such as Modal, Fly.io, Vercel Sandbox, Daytona, or E2B, with your Codex sign-in copied to the VM.
  • A structured view of Codex. Codex sessions can run as a native Chat transcript or in a terminal, and you can switch between the two without restarting the agent.
  • One inbox for every agent. Codex and Claude Code sessions, and any script that runs dev notify, report to one notification inbox that rings the pane needing you; Shift-Command-U jumps to the next one.
  • Review and verification. Code review with Codex, Claude, CodeRabbit, or Greptile against the same diff, an agent-drivable browser, and usage meters for several Codex logins through CODEX_HOME.

The tradeoffs: Agentastic runs only on macOS 14 or later (Apple Silicon and Intel). Because it drives the CLI, desktop-app features such as Handoff, local environments, and Codex on mobile stay in OpenAI's app. If Codex is your only agent and the desktop app fits, use it. For a closer look, see Agentastic vs the Codex app.

Sources and further reading#

First-party sources, first reviewed October 5, 2026 and re-checked November 14, 2026:

Continue the research:

Frequently asked questions#

Is the Codex app now ChatGPT?#

Effectively, yes. On July 9, 2026, OpenAI merged the Codex app into the ChatGPT desktop app for macOS and Windows, where Codex keeps its own coding view next to Chat and Work. Select Codex in the app to get the same workspace, including worktrees, Git review, and scheduled tasks.

Should I use the Codex app or the Codex CLI?#

Use the desktop app for parallel chats with Handoff, visual diffs, scheduled tasks, and cloud tasks in one window. Use the CLI for terminal work, scripting with codex exec, CI, and servers; it has managed worktrees too. Both use the same account and share MCP configuration.

Does the Codex app run on Windows and Linux?#

Yes. On Windows, the ChatGPT desktop app runs Codex natively in PowerShell with a Windows sandbox, or inside WSL2. On Linux it is a preview for Ubuntu 24.04 and 26.04, Debian 13, Fedora 43 and 44, and Arch Linux on x64 and ARM64, without Computer Use. The CLI runs on all three.

What is the difference between Codex local and worktree?#

Local works directly in your project checkout, while Worktree creates a separate Git worktree so Codex can work in the background without touching your files. Both run on your computer, and Handoff moves a chat and its code between them.

What is the difference between Codex local and cloud?#

Local and Worktree chats run on your computer with your files and tools. Cloud tasks run in a published cloud environment, keep working while your computer sleeps, and cannot see your local files, running processes, or VPN.

Can I use the Codex app with an API key?#

Partly. OpenAI's sign-in guide lists API-key sign-in for the desktop app, the CLI, and the IDE extension at standard API rates, while its pricing page lists the CLI, SDK, and IDE extension. Either way, cloud features such as Codex Cloud, GitHub code review, and Slack need a ChatGPT plan.

Can the Codex app run Claude Code or other agents?#

No. The desktop app, CLI, and IDE extension all run OpenAI's Codex agent. Codex can use other model providers and import setup from Claude Code or Cursor, but running Claude Code itself beside Codex takes a separate multi-agent tool, such as Agentastic or Paradev.