OpenAI Codex Guide

What it is

OpenAI Codex is OpenAI's agentic coding suite. It's not a single product — it's three:

1. codex CLI — a terminal-native agent that runs locally, reads your repo, edits files, runs commands. Same shape as Claude Code or Aider.
2. Codex Cloud — a delegated background agent. You describe a task, it runs in an isolated cloud sandbox, and returns a pull request when done. You can fire off multiple in parallel.
3. IDE plugins — first-class extensions for VS Code and JetBrains for inline edits, chat, and Codex Cloud task spawning from your editor.

All three are powered by GPT-5 family models (with Codex-tuned variants for coding). All three are included in paid ChatGPT plans — there's no separate Codex subscription line for typical use.

If you've used Claude Code, the closest analogy is: Codex CLI ≈ Claude Code, plus Codex Cloud (which Claude doesn't have a direct equivalent for), plus the deepest IDE plugin story of any major agent in 2026.

When to reach for Codex

Use Codex when:

• You're already on ChatGPT Plus / Pro — it's included
• You have parallelizable tasks — fire 5 Codex Cloud PRs simultaneously
• You want to delegate background work — kick off a task in Slack or the CLI, come back to a PR
• You're in JetBrains or want a polished VS Code plugin (not a fork like Cursor/Windsurf)
• You want to A/B GPT vs Claude on coding tasks — different strengths, useful comparisons

Don't use Codex when:

• You need the strongest single-task agent loop — Claude Code still leads on hard, multi-step interactive work
• Your stack depends on a long-tail MCP server — Claude Code's MCP ecosystem is deeper
• You need self-hosting — Codex Cloud is hosted-only
• You're allergic to OpenAI's ecosystem politics or breaking-change cadence

Setup

codex CLI

# npm
npm install -g @openai/codex

# Homebrew
brew install codex

Sign in with your ChatGPT account:

codex auth

Then run codex from any git repo. First-launch flow:

1. It detects the repo and offers to read it.
2. Pick an approval mode (auto / suggest / read-only).
3. Type a task.

Codex Cloud

Codex Cloud lives at chatgpt.com under the Codex tab, or you can fire tasks from the CLI:

codex cloud submit "Add input validation to all /api routes using zod"

The task runs in an isolated sandbox, executes against a clone of your repo, and opens a pull request when done. You'll get a Slack notification (if configured) or an email.

IDE plugins

• VS Code: install "OpenAI Codex" from the marketplace
• JetBrains: install from the JetBrains plugin marketplace

Both authenticate with your ChatGPT account and offer:

• Inline edits (Cmd-K / Alt-Enter)
• Chat panel with full project context
• One-click "send to Codex Cloud" for any selection or file

AGENTS.md

Drop an AGENTS.md at the root of your repo (and/or subdirectories). Codex reads it automatically. Same role as CLAUDE.md for Claude Code:

# AGENTS.md

## Stack
- Next.js 15 / TypeScript strict / Tailwind
- Vitest for tests, Playwright for e2e

## Conventions
- Components: PascalCase, files match component name
- API routes: validate input with zod
- Errors: typed Error subclasses, never throw strings
- Tests: colocate with source file (foo.ts + foo.test.ts)

## Commands
- Test: npm test
- Build: npm run build
- Lint: npm run lint --fix

The AGENTS.md convention is now widely adopted — it works for Codex, Cursor (with rules import), and several other agents in 2026.

The Codex CLI loop

Same shape as Claude Code: type a task, Codex reads/edits/runs/iterates. Differences:

• Approval modes are explicit and per-session: --auto (Codex applies edits without asking), --suggest (proposes diffs, you accept/reject), --read-only (reads + reports, doesn't edit).
• Resume + branch — pause a Codex session, edit manually, then codex resume to continue from your edits.
• Headless mode for CI — codex run --prompt-file task.md --output-format json is the standard pattern.

For interactive coding, the loop feels similar to Claude Code. As of mid-2026, Claude Code edges out on raw "got it right first try" rates on hard tasks, but Codex CLI is close enough that ecosystem and pricing usually drive the choice.

Codex Cloud (the novel piece)

This is where Codex genuinely differs from Claude Code. You describe a task, it runs in an isolated cloud sandbox, and returns a PR. Patterns it shines on:

1. Parallelizable small fixes

You have 5 small bugs to fix. Instead of doing them serially in Claude Code, fire 5 Codex Cloud tasks. Each gets its own sandbox, branch, and PR. Review and merge in any order.

2. Background work while you focus

You're deep in a Cascade or Claude Code session. You realize the README is out of date. Instead of context-switching, fire a Codex Cloud task: "Update the README to reflect the changes in commits since X." Come back to a PR.

3. Slack-triggered tasks

Codex Cloud integrates with Slack. Post @codex Update the changelog with recent PRs and it files a PR. Great for team workflows where non-engineers can trigger small tasks.

4. Scheduled / recurring work

Pair Codex Cloud with cron or GitHub Actions: "Every Monday, find dependencies with new minor versions and open an upgrade PR." The sandbox model fits this well.

Caveats

• You can't watch and steer mid-task. Once submitted, you wait for the PR. If the agent went off-script, you find out at the end.
• Clean repo state needed. Codex Cloud doesn't handle dirty working trees well — submit from a clean branch.
• Test suite matters more. Since you can't course-correct mid-task, the test suite is your only guardrail. Bad tests = bad PRs.

IDE plugins

Two flavors:

• Inline edit (Cmd-K / Alt-Enter) — select code, describe a change, Codex rewrites in place. Fast for one-off tweaks.
• Chat panel — full project context, multi-turn conversation. Can spawn Codex Cloud tasks from any reply.

The plugins are notably more polished than community alternatives. If you're committed to JetBrains specifically, Codex has the strongest plugin story of any major agent in 2026 — Claude Code is terminal-only and Cursor/Windsurf are VS Code forks.

Model picker

Codex uses GPT-5 family models with Codex-tuned variants:

• GPT-5 (general) — default for most tasks
• GPT-5 Coder — tuned for coding, better at multi-file edits
• GPT-5 Mini — fast and cheap, good for autocomplete + glue
• o4 reasoning — for hard architecture / debugging work where "think harder" helps

The codex CLI's --model flag swaps mid-session. Codex Cloud auto-selects based on task complexity.

Cost discipline

Codex usage is included in ChatGPT subscriptions — no per-token billing for typical use. Heavy users (CI automation, hundreds of daily Codex Cloud tasks) can hit fair-use limits and may need API-key access for the overflow.

Practical tactics:

• Use Codex Mini / GPT-5 Mini for autocomplete-heavy work. Save the big models for hard tasks.
• Don't fire 50 parallel Codex Cloud tasks. Stay within fair use.
• For automation, use the API. The codex CLI's OPENAI_API_KEY mode lets you bill against an API key instead of subscription — useful for CI.

Security & sandboxing

• codex CLI runs locally with your file/network access. Use approval modes to gate edits; configure a tool allow-list in ~/.codex/config.json.
• Codex Cloud runs in OpenAI's isolated sandbox — can't touch your local machine. Repo is cloned in, PR comes out via GitHub.
• IDE plugins run inside your editor's sandbox; same posture as any VS Code/JetBrains extension.
• For sensitive repos, set up a fine-scoped GitHub App for Codex Cloud rather than a personal access token.

Honest limitations

• Single-session agent loop is behind Claude Code on hard tasks. Codex closes the gap each quarter; as of mid-2026, Claude Code is still the pick for the hardest interactive work.
• Codex Cloud's PR-back model has a longer feedback loop. You can't steer mid-task. Plan for re-runs.
• MCP ecosystem is smaller. Common servers work; long-tail community MCP servers tend to be Claude Code-first.
• No live token meter in the CLI. Forecast cost via your ChatGPT account dashboard.
• Self-hosting isn't available. Codex Cloud is hosted-only; CLI talks to OpenAI's API.
• OpenAI's breaking-change cadence has historically been faster than Anthropic's — invest in workflow recipes carefully.

Comparison: Codex vs Claude Code vs Cursor

Most engineers running multiple use Codex Cloud + Claude Code: Codex Cloud for parallel/delegated, Claude Code for synchronous deep work. Or Codex IDE plugin + Claude Code for the JetBrains-first crowd.

Workflow patterns that work

1. AGENTS.md first, code second. 15 minutes of writing rules saves hours of agent re-runs.

2. Codex Cloud for parallel batches. When you have 3+ independent tasks, parallelize them through Cloud. Don't serialize in your CLI.

3. CLI for interactive deep work. When you need to steer mid-task, use the CLI with approval mode "suggest." Same discipline as Claude Code plan mode.

4. IDE plugin for inline edits. Don't fire up the full agent for a one-line tweak. Cmd-K and move on.

5. Slack integration for cross-team tasks. "@codex Update the README" from a non-engineer is a real productivity unlock.

6. GitHub App, not personal token. For Codex Cloud, install a properly scoped GitHub App so the agent's PR permissions are auditable.

When to walk away

• You want the strongest interactive agent loop — Claude Code wins.
• You want a unified editor experience — Cursor or Windsurf, not Codex's IDE plugin.
• You want self-hosting — none of the three big agents truly offer this; look at Continue + local model.
• You want a model-agnostic agent — Aider, Continue.
• You want minimum vendor lock-in to OpenAI — Claude Code or model-agnostic options.

Next steps

• Install the codex CLI: npm install -g @openai/codex and run codex auth.
• Write an AGENTS.md for your current project.
• Try a Codex Cloud task on a low-stakes refactor — get a feel for the PR-back loop.
• If you're in JetBrains, install the Codex plugin — best agent IDE plugin available in 2026.
• Pair Codex Cloud + Claude Code for the strongest combined setup.