Codex: The Complete Guide

What This Section Is About

Codex is OpenAI's agentic coding product. Not a chat window for code questions. Not a tab inside ChatGPT. It's a single coding agent that signs in with your ChatGPT account and runs across a terminal CLI, an IDE extension, a desktop app, a cloud workspace at chatgpt.com/codex, a Chrome extension, the ChatGPT mobile app, and GitHub, Slack, and Linear bots. OpenAI's own tagline for it is "One agent for everywhere you code." That's actually accurate: there are more surfaces than any competing tool.

This guide is for intermediate to advanced technical users who want to understand what Codex can do, how its sandbox and approval model actually works, how to drive it across surfaces without burning your quota, and how it compares to the obvious alternative. For background on the OpenAI ecosystem it sits inside, see Platform Breakdown. For the parallel Anthropic product it's most often compared to, see Claude Code: The Complete Guide.

Note: This guide assumes you're comfortable on the command line and inside a real codebase. If you don't write code yourself, this is the wrong tool, and you want no-code automation or the broader building apps section instead.

What Codex Is and Why It's Different

First, a disambiguation, because this confuses everyone.

The original "Codex" was a 2021 OpenAI language model (code-davinci-002 and friends) that powered early GitHub Copilot. That model was deprecated in March 2023 and is gone. The product in this guide is a completely separate thing that OpenAI launched in May 2025 and reused the brand name for. It is not a model. It is an agentic coding product: a software-engineering agent with a CLI, an IDE extension, a desktop app, a cloud workspace, a browser extension, mobile remote-control, and ChatOps integrations. Same name, fundamentally different thing. If you're skimming docs or third-party posts and something sounds inconsistent, that's why.

Codex is also not ChatGPT. ChatGPT is the general-purpose chat product at chatgpt.com. Codex is the coding agent that ships bundled with paid ChatGPT plans (Plus, Pro, Business, Edu, Enterprise) and now with the free tier on the smallest quota. The line that matters is on the Codex landing page: "ChatGPT Plus, Pro, Business, Edu, and Enterprise plans include Codex." Same account, separate surface, separate usage quota.

What Codex does:

• Reads and writes files anywhere on your system (subject to sandbox config)
• Runs terminal commands, builds, tests, package managers, git
• Spawns subagents for parallel work
• Delegates long-running tasks to OpenAI's cloud infrastructure and comes back with a PR
• Reviews and edits PRs directly inside GitHub via @codex review
• Takes Linear and Slack mentions as task triggers
• Drives your actual computer: real Chrome browser, real native apps via OS-level computer use, real desktop GUI
• Remote-controls your Mac from your phone: approve commands, change models, kick off new tasks while you're away from your machine

Why people care: as of May 7, 2026, OpenAI publicly reported more than 4 million weekly active Codex users, up 8x since the start of the year. For an agentic developer tool barely a year out of preview, that's a lot of adoption.

What makes it different from chat-based coding: Codex doesn't hand you a snippet to paste. It does the work. It picks the files, edits them, runs the tests, opens the PR. This is the same agentic shift covered in agentic AI, applied specifically to software engineering. If you've only used AI for code suggestions inside your editor (the model covered in AI in your tools), the mental shift required here is real.

What makes it different from other coding agents: Codex is the only mainstream coding agent that can genuinely operate your computer. GPT-5.4 (March 5, 2026) was the first OpenAI model with native computer use, and that capability ships across the surfaces: the macOS desktop app can drive native apps and the system GUI, the Chrome extension drives your real signed-in browser, and the mobile remote-control feature (May 14, 2026) lets you do all of that from your phone. The tagline OpenAI used for the May 14 launch is literal: "work with Codex from anywhere". Claude Code can drive a browser via Claude in Chrome and recently added experimental computer use, but Codex's coverage is broader and more central to the product.

The honest tradeoff up front: Codex is powerful but its pricing model is volatile, its quota accounting has been buggy in May 2026, and there are surfaces where Claude Code is genuinely better. Both can be true. The honest comparison is at the end of this guide.

The Surfaces

The defining shape of Codex is that it isn't one thing. It's the same agent, with the same threads and config, reachable from nine different places. You sign in once with ChatGPT, and your AGENTS.md files, MCP servers, skills, plugins, and conversation history follow you across surfaces. This is the part the marketing tagline is actually selling, and it works.

Codex CLI

The original surface. Open source, Rust-based, lives at github.com/openai/codex.

Install on macOS or Linux:

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

Windows (native PowerShell):

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

Or via npm: npm install -g @openai/codex. Or via Homebrew: brew install --cask codex. Full install matrix in the install docs. Current stable as of May 21, 2026 is 0.133.0, per the release notes.

Auth on first run: a prompt asks you to either "Sign in with ChatGPT" or paste an API key. ChatGPT sign-in is the right default for almost everyone, because it uses your bundled Codex quota instead of billing you per token. API-key auth bills against your OpenAI API account separately and disables some features like cloud threads. See the quickstart for the full flow.

The TUI exposes slash commands inside the session: /model swaps the active model, /agent inspects subagent threads, /status shows your current quota windows, /goal enters Goal mode, codex resume continues a previous thread, codex exec runs Codex non-interactively for scripting, codex mcp manages MCP servers, and codex doctor diagnoses install problems. Image inputs work via --image. The CLI is the most scriptable surface and the one you'll write automations against.

IDE Extension

A single extension that ships under several IDE marketplaces: VS Code and VS Code Insiders, Cursor, Windsurf, and the JetBrains family (IntelliJ, PyCharm, WebStorm, Rider). JetBrains went through a phased rollout starting March 2026.

Inside the extension there are three operating modes, presented as buttons: Chat, Agent, and Agent (Full Access). These aren't separate products, they're labels for combinations of sandbox mode and approval policy. Chat is read-only. Agent is workspace-write with on-request approvals. Agent (Full Access) skips everything. The mapping is documented in the Approvals and Sandbox section below, and it's the single most important thing to internalize about Codex.

Settings sync between the IDE extension and the desktop app, added in late March 2026. Slash commands work inside the IDE the same way they work in the CLI. You can bind IDE commands to keystrokes for things like "toggle Codex chat" or "add current file to context."

Codex Web

The cloud-hosted version. Canonical URL is chatgpt.com/codex. Worth memorizing because there's a graveyard of dead URLs people get wrong: code.openai.com is not it, codex.openai.com is not it. The cloud docs live at developers.openai.com/codex/cloud.

What Codex Web does: it runs Codex tasks in OpenAI-managed isolated containers, in parallel, against connected GitHub repos. The output of a cloud task is typically a new PR. Each repo gets one or more configurable "environments" that specify setup steps, allowed tools, and an internet-access policy (off by default, opt-in per environment with domain and HTTP-method allowlists).

The clever part: tasks launched from your CLI, IDE, desktop app, Slack, Linear, GitHub, or the web all converge to the same cloud workspace. You can kick off a task from your terminal, watch it on the web, approve a command from your phone, and pick up the resulting PR in GitHub.

Codex Desktop App

Distinct from both the CLI and the IDE extension. Project-oriented, with a sidebar of parallel threads, baked-in Git worktrees, automations, voice dictation, an in-app browser, Chrome extension management, Remote SSH, an artifact viewer for PDFs and spreadsheets, a GitHub PR inspector, and (on macOS) Memories and Chronicle.

• macOS: launched February 2, 2026, Apple Silicon and Intel DMG builds.
• Windows: launched March 3, 2026 via the Microsoft Store. Native PowerShell integration, Windows Sandbox, optional WSL.
• Linux: still on a waitlist as of May 2026 per the quickstart page. No date.

If you spend more than a couple of hours a day in Codex, the desktop app is the surface that benefits you most. The CLI is more scriptable; the desktop app is more capable.

GitHub Integration

Codex's GitHub integration sits on top of Codex Cloud. The pattern: comment @codex review on a PR, Codex reacts with an eyes emoji, and a GitHub-native review appears flagging "only P0 and P1 issues." Settings live at chatgpt.com/codex/settings/code-review.

Auto-Review can be enabled to run on every new PR without a manual mention. Follow-up fixes work too: comment @codex fix the P1 issue and Codex can push corrections to the branch when permissions allow.

Codex respects ## Review guidelines sections inside AGENTS.md, and it applies the closest AGENTS.md to each changed file. For polyglot or monorepo projects, this is the right place to encode review standards.

@codex fix the CI failures on a PR or issue triggers a cloud task with the issue or PR as context; the result comes back as a new PR. GitHub integration plus @codex went GA October 22, 2025, shortly after Codex itself hit GA on October 6, 2025.

Mobile (via the ChatGPT app)

Launched May 14, 2026. Codex remote-control lives inside the ChatGPT mobile app, not a standalone Codex app. Pairing is QR-based: open the Codex desktop app on your Mac, hit "Set up Codex mobile," scan from your phone. Details at developers.openai.com/codex/remote-connections.

From the phone you can browse threads, review outputs, approve commands, change models, start new threads, and get push notifications when Codex needs you. Nothing actually runs on the phone; files, credentials, and permissions all stay on your Mac. The phone is a thin client over a secure relay. Windows mobile pairing is listed as "coming soon."

Combined with Auto-Review, cloud delegation, and Codex's computer use (below), the mobile surface materially changes how much in-flight work you can hold. You can kick a Codex task off on the subway, watch it click through a real Salesforce session, approve the next step at the coffee shop, and merge the PR before you get home.

Chrome Extension

Launched May 7, 2026. Lives inside the Codex desktop app's Plugins panel. Lets Codex drive a real, signed-in Chrome session to interact with LinkedIn, Salesforce, Gmail, internal admin tools, anywhere a plugin API doesn't suffice. Docs: developers.openai.com/codex/app/chrome-extension. Listing: Chrome Web Store.

Importantly, the extension doesn't hijack your browser. It groups Codex activity into its own isolated tabs, and a May 21 update cleaned up the tab-clutter problem. You keep working in other tabs. Per-site approval is required on each new host (allow once, always allow, or decline), and allowlists/blocklists live in Computer Use settings.

Region availability: live everywhere except the EU and UK at launch. Same restriction applies to Computer Use and Chronicle. OpenAI says "support coming soon."

Computer Use

Codex doesn't just edit files. It can run your computer. This is the capability that ties the Mac app, the Chrome extension, and mobile remote-control into one story, and it's the cleanest single differentiator versus other coding agents.

What it can actually drive:

• The macOS GUI. Codex's Mac desktop app can click, scroll, type, and read the screen across native applications. Useful for design tools, admin consoles that ship as native apps, or any workflow that lives partly outside the terminal. macOS first, Windows next per the Codex changelog. GPT-5.4 was the first model with native computer use baked in.
• Your real Chrome browser. The Chrome extension drives your signed-in session, so Codex sees Salesforce as you, sees Gmail as you, and acts inside web apps that have no usable API. Per-site approval gates each new host.
• Your machine, from your phone. With mobile pairing, you can approve computer-use steps, review screenshots, and redirect Codex from the ChatGPT app while you're away from your laptop. The compute runs on your paired Mac; the phone is the remote.

Why this matters: most coding work touches things that aren't code. Filing tickets in Linear, checking analytics dashboards, updating CRM records, clicking through an OAuth consent screen for a service you're integrating. Other coding agents either ignore those steps or hand them back to you. Codex can run them inside the same thread, with the same approval model and audit trail.

The honest limits. Computer Use is not available in the EU, UK, or Switzerland at launch. Chronicle (the macOS Memories feature that logs computer-use activity for replay) ships off by default and has raised real privacy concerns from people whose Macs are shared or audit-monitored. And per-site allowlists are only as strong as the human approving them; if you click "always allow" on internal-admin.example.com, Codex can do anything that session can do. Sandbox this aggressively if you have any doubt.

For a broader take on agentic computer-use risks and how to think about granting any agent access to your accounts, see privacy and security.

Slack and Linear

Codex in Slack (GA October 6, 2025): install the workspace app, add @Codex to a channel, mention it. Codex reads thread context, picks the best environment, defaults to the first repo in the environment map, posts a Codex Cloud task link, then replies in-thread with the result. Enterprise admins can disable answer-posting if they only want the task link.

Codex in Linear (GA December 4, 2025): connect GitHub, create an environment, install Codex-for-Linear. Assigning a Linear issue to Codex (or @Codex-mentioning) spins up a cloud agent that posts status updates back to the issue and ends with a PR link. Linear triage rules can auto-delegate new issues. For local CLI work against Linear, configure the Linear MCP server: codex mcp login linear and edit ~/.codex/config.toml.

Worth a brief mention: in April 2026, OpenAI released Symphony, an open-source orchestration spec that turns a Linear board into a control plane for many parallel Codex agents. It's a reference implementation, not a maintained product. Per Help Net Security's coverage, it reportedly drove a 500% increase in landed PRs at OpenAI in its first three weeks. If you have a Linear-heavy team and engineering bandwidth to maintain it, the spec is worth reading.

Getting Started

Skip the conceptual stuff for a minute and get something working.

1. Install the CLI:

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

# or
npm install -g @openai/codex

2. Sign in:

codex login

This opens a browser. Choose "Sign in with ChatGPT" and approve. Your tokens land in ~/.codex/. If you need to relocate that, set CODEX_HOME.

3. First real run:

cd /path/to/your/project
codex

You land in the TUI. Your default sandbox mode is workspace-write, your default approval policy is on-request. Codex can read, edit, and run commands inside the project; it'll ask before touching anything outside it or going to the network.

4. Try a real task:

You: Read the README and the package.json. Tell me what this project does
and what the dev workflow is.

Codex: [reads files, summarizes]

You: Add a `--verbose` flag to the CLI entrypoint that logs every step.
Add a unit test for it. Run the tests and confirm.

Codex: [edits files, runs tests, reports back]

If the tests fail, Codex reads the failure, fixes the code, and re-runs. You don't drive each step; you set the goal and review the result.

5. Useful slash commands inside the TUI:

• /model: swap the active model mid-session
• /status: current quota windows and limits
• /agent: inspect subagent threads
• /goal: enter Goal mode (persistent agent loop)
• /profile: switch to a named config profile