Codex: a practitioner’s field guide.

What "Codex" means in 2026

"Codex" has been several different products at OpenAI over five years. If you don't know which one someone is talking about, you'll guess wrong half the time. The current state, as of September 2026:

• Codex CLI: a terminal coding agent, OpenAI's answer to Claude Code. You install it, you run codex, it edits files in your repo, it iterates on code. Local, sandboxed, runs against your laptop. Open source (Apache-2.0) on GitHub.
• Codex in the ChatGPT desktop app: since July 9, 2026, the ChatGPT desktop app for Mac and Windows has three modes (Chat, Work, and Codex), and Codex mode is what used to be the standalone Codex app. It's the same local agent with a GUI: diffs, inline annotations, and GitHub PR review in the sidebar.
• Codex IDE extensions: the same agent in VS Code (and forks like Cursor and Windsurf) and JetBrains IDEs. They run the agent locally against your open project, and can hand longer jobs to the cloud.
• Codex cloud: the agent at chatgpt.com/codex. You connect a GitHub repo, give it a task, and it works in a cloud sandbox to produce a pull request. Parallel-capable, runs in OpenAI's environment. You can also trigger it from GitHub, Slack, and your IDE.

(The Codex API from 2021, the original code-completion model, was deprecated in 2023 and is gone. If you read an article that mentions "Codex" without a date, suspect the article.)

The models, as of late September 2026

Two model generations landed since the last update of this guide:

• GPT-6 Sol (gpt-6-sol, September 22): the new default in Codex. OpenAI calls it its daily driver for complex coding and agentic work.
• GPT-6 Luna (gpt-6-luna, September 22): the fast, cheap sibling for high-volume and simple tasks.
• GPT-6 Astra (September 3): OpenAI's most capable model, and the one it describes as its best for software engineering to date. It costs the most allowance per task; access depends on your plan.
• GPT-5.6 Sol, Terra, and Luna (July 9): the previous family, still selectable.

The thing to internalize: the local surfaces and the cloud agent are not competitors. They're collaborators. The CLI, desktop app, and IDE are for the work you want to watch happen on your machine. The cloud agent is for the work you want to outsource to a sandbox while you do something else. Knowing when to reach for which is the whole game.

The Codex CLI

If you've used Claude Code, the Codex CLI will feel familiar in shape: a terminal-resident agent that reads your repo, plans changes, edits files, and runs commands inside a sandbox. The vocabulary is different but the loop is the same. Prompt, plan, edit, verify, repeat.

Install & run

Codex CLI ships as a single native binary (it's written in Rust) for macOS, Windows, and Linux. Use the official installer, npm, or Homebrew. On Windows you have two paths: native PowerShell with Codex's own Windows sandbox, or WSL2 for a Linux-native environment. Both work; pick based on which one matches your existing dev setup.

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

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

# or via a package manager
npm install -g @openai/codex     # note the @openai/ scope
brew install --cask codex

# Verify, then pick "Sign in with ChatGPT"
codex --version
codex

Sign in with your ChatGPT account to use your plan's allowance, or with an API key if you'd rather pay per token. Then run /init in a project to generate an AGENTS.md. Just like Claude Code's CLAUDE.md, this is the project-level instructions file. Unlike CLAUDE.md, AGENTS.md is cross-tool. Codex, Cursor, Aider, and an increasing number of other agents all read the same file. If you've ever wanted one config file your tools agree on, this is the closest thing to it. Coming from Claude Code? /import pulls your setup, the current project, and recent chats across.

The model picker

Codex CLI lets you switch models and reasoning effort with /model, or at launch with codex --model <name>. As of late September 2026:

• GPT-6 Sol (gpt-6-sol): the default. Strong enough for nearly everything.
• GPT-6 Luna (gpt-6-luna): faster and far cheaper against your allowance. Good for repetitive edits, scripted runs, and quick questions about the codebase.
• GPT-6 Astra: the heavyweight for the hardest problems. It burns through your allowance fastest, so reach for it deliberately.
• GPT-5.6 Sol / Terra / Luna: last generation, still available if you've tuned prompts or scripts around them.
• Reasoning effort: chosen in the same /model menu; higher effort tells the model to think longer before acting.

For most tasks, leave it on GPT-6 Sol at medium effort and don't worry about it. The effort lever matters when you're doing something genuinely novel: refactors that span the codebase, debugging that needs hypotheses, architectural changes. For tweaks, low or medium is faster. Pin the model in ~/.codex/config.toml (model = "gpt-6-sol") if you want the same one every time.

Sandboxing

Codex CLI's sandbox is one of its strongest features. By default, every command Codex wants to run is constrained:

Two settings control what Codex may do, and /permissions changes them mid-session:

• Sandbox mode (--sandbox): read-only (look, don't touch), workspace-write (edit files in the working directory and any --add-dir roots, no network; the everyday choice), or danger-full-access (no sandbox at all).
• Approval policy (--ask-for-approval): untrusted (ask before anything not known-safe), on-request (the model asks when it needs to go beyond the sandbox), or never (don't ask; used for scripted runs).
• --dangerously-bypass-approvals-and-sandbox (alias --yolo) turns both off. The help text calls it "extremely dangerous" and intends it only for environments that are already sandboxed, like a throwaway container.

(--profile exists too, but it layers a named config file on top of your base config; it isn't a permission level.)

The CLI loop in practice

Day-to-day, the loop looks like this:

1. You're in a project. You run codex.
2. You describe the task: "Add a search box to the header that filters the list view as I type."
3. Codex plans the change (or, for bigger jobs, you switch to Plan mode with /plan first and agree on the plan).
4. It edits files, runs your tests (if it found them), and reports back.
5. You inspect the diff, accept or reject, iterate.

Useful slash commands inside the session:

• /model: choose the model and reasoning effort.
• /permissions: change what Codex is allowed to do (sandbox and approvals).
• /plan: switch to Plan mode before touching anything.
• /goal: set a completion condition for a long-running task ("stop when the checkout tests pass").
• /diff: show the git diff, including untracked files.
• /review: have Codex review your current changes and look for issues.
• /compact: summarize the conversation before you hit the context limit.
• /fork, /resume, /worktree: branch the chat, pick up a saved one, or start the conversation in a fresh git worktree.
• /mcp, /skills, /hooks, /plugins: the extension points (more below).
• /status and /usage: session config, token use, and how much of your plan's allowance is left.

How it differs from Claude Code

The honest comparison, from someone who uses both:

I've dropped the benchmark row this guide used to carry. Both vendors shipped new model generations in the last few months, each claims leads on different leaderboards, and a number here would be stale within weeks. Check the vendors' current announcements if a benchmark matters to you.

Both tools are excellent. The differences are real but smaller than the marketing material suggests, and the extension models have converged a lot this year. Most engineers who use both end up keeping both: Claude Code for ambitious feature work and code review, Codex for terminal automation and "I trust the sandbox enough to walk away" tasks.

Codex cloud (chatgpt.com/codex)

The cloud agent is the more transformative product, even if the CLI gets more attention. It's the first widely available "agent that opens PRs" that actually works for the everyday case.

The model

You connect a GitHub repository (or repositories) and give Codex a task (typically as an issue link or a prose description). Codex spins up a sandboxed cloud environment with your repo preloaded. It works through the task in the background. When it's done, you get a pull request with the changes, ready for review.

What's different from "let me autocomplete in my IDE":

• Tasks run in parallel. You can dispatch four tasks across four cloud sandboxes; you don't sit at your machine waiting for one to finish.
• Tasks have their own environment. Codex installs your dependencies, runs your tests, and iterates against them, all without touching your laptop.
• Tasks produce reviewable artifacts. The output is a PR, not a chat transcript. The diff is the deliverable.
• Tasks can be reviewed and re-run. If the PR isn't right, you leave a comment ("the test for X is wrong because…") and Codex iterates.

The dispatch loop

1. From chatgpt.com/codex, the desktop app, your IDE extension, a GitHub comment, or an @Codex mention in Slack, you create a task.
2. Codex picks up the task and starts a fresh sandbox with your repo cloned. The environment's setup script runs first (with internet on, so it can install dependencies); by default the agent itself then works with internet off.
3. It iterates: write code, run tests, inspect failures, fix, retry. Most non-trivial tasks involve several internal iterations.
4. When it converges (or gives up), it pushes a branch and opens a PR.
5. The task card in your dashboard shows status badges: draft, open, merged, closed.
6. You review the PR like any other PR. Comments → iteration. Merge → done.

Skills, and code review on GitHub

Skills are reusable, packaged instructions the agent can apply across tasks: code understanding, documentation, code review, migrations, your team's conventions ("follow our error-handling pattern," "always add types in this style"). They're no longer a cloud-only feature; the CLI (/skills), the desktop app, and the IDE extensions use them too.

The mental model: AGENTS.md is the always-on briefing; Skills are the procedures the agent pulls in when a task calls for them. Both are encoded team conventions that travel with the code, not with the engineer.

The other cloud feature worth turning on is code review. Once the Codex GitHub integration is set up, comment @codex review on a pull request and Codex posts a review summary and inline findings. It's a cheap second reviewer for PRs from humans and agents alike, and it's included from Plus up.

Where the cloud agent shines

• Routine PRs that aren't worth your attention: dependency bumps with non-trivial code changes, lint cleanups, test scaffolding, simple migrations.
• Bugs with a reproduction: file an issue with a failing test, dispatch to Codex, get a PR back.
• Documentation drift: "the README is out of date for these features" works well as a Codex task.
• Parallel exploration: dispatch four variations of a feature implementation; pick the one whose PR you like best.
• Things that need a long sandboxed run, like large refactors, codebase-wide rename operations, or multi-step investigations, where you don't want to babysit a CLI.

Where the cloud agent struggles

• Tasks with unclear acceptance criteria: if you can't write a failing test, the cloud agent guesses at what "done" means. The result is plausible but often wrong in subtle ways.
• Tasks requiring context the agent can't see: secrets, private services, custom build steps, anything that needs the network after setup. The sandbox is isolated by design.
• UI work: the cloud agent can write the code, but judging whether the result looks and feels right still usually requires a human running the change locally.
• Codebases with custom toolchains that aren't in the sandbox image. You can extend the image, but it's friction.

Desktop app and IDE extensions

This is the part of Codex that changed most since spring, and the part earlier versions of this guide got most wrong.

IDE extensions

Codex extensions exist for VS Code (and VS Code forks such as Cursor and Windsurf) and for JetBrains IDEs (IntelliJ IDEA, PyCharm, WebStorm, Rider and friends). The framing that matters:

• The extensions run the same agent as the CLI, locally, against the project you have open. It reads your open files, edits them, and runs commands, under the same sandbox and approval rules.
• They also delegate to the cloud: hand a longer job to Codex cloud, keep working, and review the resulting diff or PR without leaving the editor.
• Same account, same models, same AGENTS.md, same allowance as every other surface.

Codex mode in the ChatGPT desktop app

Since July 9, 2026, the standalone Codex app has become Codex mode in the ChatGPT desktop app (Mac and Windows), next to Chat and ChatGPT Work. Work and Codex share plugins; Codex mode simply shows the technical detail Work hides. The parts worth knowing:

• Reviewing agent output: edit Markdown and code directly in the app, annotate inline, and ask Codex to revise just the selection.
• PR review in the sidebar: GitHub pull requests with reviewer feedback alongside the diff.
• Handoff from the terminal: /app in the CLI continues the current session in the desktop app, which is handy when a terminal session turns into a long review.

The mental model that works: the terminal, the IDE, and the desktop app are three windows onto one local agent; the cloud is the one you send away. Pick the window that matches where your attention already is.

Choosing between CLI and cloud (and Claude Code)

Most engineers using Codex seriously end up running both flavors plus Claude Code. The split:

Limits and pricing

Pricing

Codex is included with ChatGPT plans, and every surface (CLI, desktop app, IDE, cloud) draws on the same allowance. As of September 2026:

• Free / Go: the desktop app is available on every plan, but full Codex (cloud delegation, GitHub code review, Slack) starts at Plus. Free and Go users can try GPT-6 Luna in the desktop app.
• Plus ($20/mo): CLI, IDE, desktop, and cloud tasks, GPT-6 Sol and Luna, GitHub code review.
• Pro $100/mo: 5× Plus usage.
• Pro $200/mo: 20× Plus usage, for people who run agents all day.
• Business: Standard seats ($20/seat/mo annual) at roughly Plus-level usage, or Premium seats ($100/seat/mo annual, added August 2026) with 5× the usage and no five-hour limit. Admin controls, shared Skills and plugins.
• Enterprise / Edu: an organization-wide credit pool instead of fixed per-seat limits, plus audit logs and admin controls.

Usage is metered against a rolling 5-hour window with weekly limits on top, and OpenAI doesn't publish exact numbers. Heavier models cost more of it: a GPT-6 Astra task eats far more than the same task on GPT-6 Luna. When you run out, you can buy credits for additional usage. Since September 9, Deep Research inside ChatGPT Work and Codex draws on the same allowance, so research-heavy weeks leave less for coding.

You can also sign the CLI in with an OpenAI API key and pay per token instead. After the September 22 price cuts that's GPT-6 Sol at $2 / $10 and GPT-6 Luna at $0.10 / $0.50 per million input / output tokens, with cached input reads heavily discounted. It's the right choice for CI pipelines and scripted runs where you want spend on a company API bill rather than a personal subscription.

Cloud task limits

• Concurrency: you can run several cloud tasks in parallel; how many depends on your plan and current load.
• Per-task runtime: long, but bounded. Tasks that need hours are better split into several.
• Repo size: large repos work, but setup gets slower; keep the environment's setup script lean.
• Branch policy: Codex creates branches under codex/ by default; configurable.
• Network access: on during the setup script, off for the agent phase by default. You can allow it per environment, ideally with a domain allowlist.

CLI limits

• Context: model-dependent, and large on the GPT-6 models. Very long sessions still degrade like any agent's. Use /compact, or /new with a short handoff note, for long-running work.
• Rate limits: the same shared allowance as every other Codex surface. /usage and /status tell you where you stand before you start a long run.
• Voice: the CLI now has a /voice command. Treat it as another way to spend the same allowance, not a free extra.

Best practices

Troubleshooting playbook

The patterns to recognize, with a short fix for each.

Closing thought

Codex in 2026 isn't one tool. It's one agent with a local side (the CLI, the desktop app, your IDE) and a cloud side. The local side is what you reach for when you want to watch the agent work; the cloud agent is what you reach for when you want to not watch. Both are useful, often in the same week, sometimes on the same task.

Use the CLI for tasks where presence is value. Use the cloud agent for tasks where absence is value. — TWD

The biggest mistake people make with Codex is using one mode for everything. CLI users dispatch a long-running cloud task and sit there waiting. Cloud users force a context-heavy debugging session through the PR-review loop. Both miss the point. The two surfaces exist because they map to two different relationships you have with a piece of work, and recognizing which relationship you're in is most of the practice.

For up-to-date model availability, sandbox modes, and feature flags: developers.openai.com/codex/changelog. The pace is high; don't trust month-old documentation on specifics.