OpenAI Codex
Part 1: One Agent, Five Surfaces
The short version
Codex is OpenAI's coding agent: it writes code, understands unfamiliar codebases, reviews changes, and automates engineering work. The CLI launched in April 2025, the cloud agent a month later, and by mid-2026 it spans five surfaces. You pick the surface per task; your AGENTS.md instructions, and your plan's usage window follow you across all of them.
Terminal CLI
Run codex for an interactive agent in your terminal. Open source (Apache-2.0) and rewritten in Rust for speed: the repo is roughly 96% Rust. Best for hands-on local work where you watch and steer.
Cloud / Web
Delegate tasks to OpenAI-managed cloud environments. Tasks run in the background, in parallel, and come back as reviewable diffs or pull requests. Connect GitHub and you can tag @codex directly in pull-request comments.
IDE extension
The same agent inside VS Code (and Insiders), Cursor, and Windsurf via OpenAI's extension; JetBrains IDEs ship their own Codex integration. It works from your editor context, edits and runs code, and can hand longer jobs off to the cloud, then pull the finished diff back into your editor.
ChatGPT desktop app
As of July 2026 Codex lives inside the ChatGPT desktop app, with direct Markdown/code editing and PR Chat for GitHub reviews. One app for chat and agentic coding.
SDK & headless
codex exec runs one-shot tasks in scripts and CI, and official SDKs (@openai/codex-sdk for TypeScript, openai-codex for Python) embed the agent in your own tools. Teams reach for this surface once Codex stops being an experiment and starts running unattended in scripts and CI.
Models: the GPT-5.6 family (July 2026)
GPT-5.6 spans three durable capability tiers: Sol the flagship, Terra the balanced mid-tier, and Luna the fast/cheap tier. The bare gpt-5.6 API alias routes to Sol. Reasoning effort is a separate dial (minimal → xhigh in CLI/API config; the app picker labels its levels Light through Ultra). Pick the tier first, and raise effort only when a task genuinely needs deeper reasoning; most edits don't.
| Model | Use it for | Codex access | API $ / 1M in · out |
|---|---|---|---|
| GPT-5.6 Sol | Flagship: hardest refactors, architecture, long agentic runs | Plus / Pro / Business / Enterprise | $5 / $30 |
| GPT-5.6 Terra | Balanced default: performance competitive with GPT-5.5 at half the price | All plans (Free & Go default here) | $2.50 / $15 |
| GPT-5.6 Luna | Fastest and cheapest: quick edits, high-volume automation, subagents | Plus / Pro / Business / Enterprise | $1 / $6 |
Pricing per million tokens: Sol $5 in / $30 out, Terra $2.50 / $15, Luna $1 / $6. A practical default for vibe coding: Terra for everyday edits, escalate to Sol when a task keeps failing, drop to Luna for bulk mechanical changes.
Plans and the usage window
Every ChatGPT tier includes Codex. Usage is metered in a 5-hour rolling window shared across local and cloud work, with optional extra credits on paid tiers.
| Plan | Price | What you get |
|---|---|---|
| Free | $0 | Codex with GPT-5.6 Terra, limited usage window |
| Go | $8/mo | Terra with a larger window |
| Plus | $20/mo | Sol / Terra / Luna + per-model reasoning effort |
| Pro | from $100/mo | 5×–20× higher limits for heavy daily agent use |
| Business / Edu / Enterprise | $20–25/user/mo · custom | Team management and cloud-managed configuration |
Part 2: The Terminal CLI
Install and first run
Three install paths, all landing on the same binary. Sign in with your ChatGPT account (recommended, uses your plan's included usage) or an API key.
Works on macOS, Linux, and Windows (native or WSL2). The first thing to do in a real project is create an AGENTS.md, covered below, so the agent knows your build, test, and style rules before it touches anything.
Approval modes: the safety dial
The three modes you'll use daily, switched with /permissions. Under the hood they map to an OS-level sandbox (sandbox_mode) plus an approval policy; the CLI names are the friendly layer. The docs also list a fourth, stricter mode, Untrusted, which auto-runs only known-safe read operations.
Read-only
Codex can browse and analyze but asks before any change or command. Start here on a codebase you care about; you approve every step.
Auto (default)
Reads, edits, and runs commands freely inside the working directory, but asks before network access or anything outside project scope. The everyday mode.
Full Access
Whole machine plus network with no confirmations. Only defensible inside a disposable VM or container. Treat it like handing over your keyboard.
Older tutorials lie: you'll still find "Suggest / Auto-edit / Full-auto" in 2025-era content. Those names are gone (--full-auto is now a deprecated compatibility flag that prints a warning), and the IDE extension calls its modes Chat / Agent / Agent (Full Access).
Session commands and shortcuts
The interactive TUI is closer to an editor than a chat window. These are the commands worth memorizing first.
/modelSwitch model (Sol / Terra / Luna) and reasoning effort mid-session/permissionsChange approval mode: Read-only, Auto, or Full Access/reviewRun code-review presets against your working tree or a diff/forkFork the current chat into a new one (Esc Esc branches from an earlier point)/sideOpen a parallel side workflow without losing your main thread/statusSession configuration and token usage/archiveArchive the current thread (codex unarchive brings it back)Esc EscEdit your previous message and re-run from there@Fuzzy file search, mention any file as contextTabQueue a follow-up message while the agent is still workingCtrl+LClear the screen (long prompts can open in your VISUAL/EDITOR editor)Ctrl+RSearch prompt historyCtrl+OCopy the last output blockAGENTS.md: your repo's README for the agent
Codex reads AGENTS.md files before doing any work. It's the Codex analogue of Claude Code's CLAUDE.md: setup commands, test commands, style rules, PR conventions. Files cascade from global (~/.codex/) through the project root down to the working directory, with the nearest file winning on conflicts.
Keep it under the 32 KiB default cap (see gotchas) and treat it like code: review changes to it in PRs, because every agent run obeys it.
Headless: codex exec
One-shot, scriptable runs: progress streams to stderr, the final message to stdout, so it pipes cleanly.
Part 3: Delegating to Codex Cloud
How a cloud task runs
Each task gets its own disposable environment built from the universal image: container boots → your repo checks out → your setup script runs (with internet) → the network policy flips to your configured default → the agent edits and validates in a loop. Containers cache for up to 12 hours, so follow-up tasks start fast.
Why it matters for vibe coders: cloud tasks run in parallel. Kick off "add dark mode," "fix the flaky signup test," and "upgrade to React 19" as three separate tasks, then review three PRs over coffee. Your laptop stays free and nothing touches your local checkout until you accept a diff (codex apply pulls one down locally).
Environment variables persist; secrets don't. Env vars carry across runs, but secrets are extra-encrypted, exposed only to setup scripts, and removed before the agent phase; the model never sees them.
GitHub-native workflow
Connect a repo and comment @codex on a pull request: @codex review runs a review, and any other mention starts a cloud task with your PR as context. A precise PR comment is all the hand-off a cloud task needs. (Cloud tasks can also start from Linear issues and Slack threads; GitHub issue comments are not a documented trigger.)
CI automation with the official Action
openai/codex-action@v1 installs the CLI and runs codex exec inside your workflow under explicit permissions. The common pattern is automated PR review that posts feedback via the GitHub API. Safety defaults are sensible: the action's safety-strategy defaults to drop-sudo, and you can pin who may trigger it with allow-users.
Part 4: Workflows, Gotchas, and Codex vs Claude
A sane default workflow
Four steps, in the order that keeps you out of trouble.
Write AGENTS.md first. Setup, test, and style rules. Five minutes here saves every future run from re-learning your repo.
Start in Auto mode locally. Pair on the risky, ambiguous work in the CLI or IDE where you watch every diff.
Delegate the mechanical backlog to the cloud. Dependency bumps, test gaps, lint sweeps, parallel cloud tasks, reviewed as PRs.
Gate everything with tests in CI. The TDD module's rules apply double to agent output: if the suite passes, the change stands; if it fails, nothing merges.
Gotchas that bite real users
OpenAI moved Codex to token-aligned pricing on April 2, 2026. A giant refactor now costs proportionally more of your 5-hour window than a one-line fix. Old per-message intuition is stale; watch the usage meter on big tasks.
The default project_doc_max_bytes is 32 KiB. Nothing warns you: instructions past the cap simply never reach the agent. Keep AGENTS.md tight, or raise the limit deliberately in config.
In Codex Cloud, setup scripts can reach the internet but the agent phase defaults to network OFF, and encrypted secrets are stripped before the agent runs. Great security default, but it explains why a cloud task can't npm install a new dependency mid-run unless you pre-install it in the setup script.
GPT-5.2 and GPT-5.3-Codex are deprecated for ChatGPT sign-ins, and older docs pages still name superseded models. When behavior looks worse than expected, check what's pinned in ~/.codex/config.toml first; the models and pricing pages are authoritative when feature pages disagree.
--dangerously-bypass-approvals-and-sandbox (alias --yolo) disables both approvals and the OS sandbox. There is exactly one sane home for it: an isolated, disposable environment that holds nothing you'd miss. Never on your laptop, never with real credentials in reach.
Codex vs Claude Code (and Cowork)
Read this as a routing guide rather than a scoreboard. Both tools are excellent; they earn their keep on different tasks.
| Dimension | OpenAI Codex | Claude Code / Cowork |
|---|---|---|
| Vendor / engine | OpenAI: GPT-5.6 family locally, GPT-5.4 in cloud tasks | Anthropic, Opus / Sonnet / Haiku |
| Repo instructions | AGENTS.md (cascading, 32 KiB cap) | CLAUDE.md (hierarchical) |
| Cloud delegation | Core strength: parallel cloud tasks, @codex on pull requests | Cloud sessions on Anthropic VMs + Remote Control |
| Extension layer | MCP client, SDKs, GitHub Action | Skills, hooks, subagents, agent teams, plugins, MCP |
| Headless / CI | codex exec + openai/codex-action@v1 | Print mode (-p) + GitHub/GitLab integrations |
| Permission model | Read-only / Auto / Untrusted / Full Access (+ OS sandbox config) | Six modes + sandboxed Bash, Shift+Tab cycling |
| Non-developer sibling | n/a (Codex is developer-focused) | Claude Cowork (same engine, simplified surface) |
| Entry price | Included from Free ($0) / Go ($8) | Pro $20/mo; Max from $100/mo |
Practical routing: reach for Codex when the win is cloud delegation (parallel background tasks, @codex on pull requests, CI review). Reach for Claude Code when the win is local depth: skills, hooks, subagent orchestration, MCP-heavy setups. If the work isn't code at all, that's Claude Cowork (module 11 in this curriculum).