OpenAI Codex: The Fourth Contender

Why this matters for you: if you finished M10 and built a hybrid stack around Claude Code + Gemini CLI + Copilot, Codex is the one tool that could displace a slot in that stack — specifically the autonomous-agent slot. It is the closest architectural sibling to Claude Code of any tool on the market, and it comes bundled "free" with a ChatGPT subscription that millions of developers already pay for. That bundling is the single biggest strategic fact about Codex: for a developer already on ChatGPT Plus, the marginal cost of trying a second autonomous agent is $0.

Codex follows the same fundamental design as Claude Code: an agentic loop in your terminal that reads your repo, edits files, runs commands, observes the output, and iterates. Where it differs is in how many surfaces share that loop and how the security boundary is drawn (Section 4).

The four surfaces

• Codex CLI — the terminal agent, open-source and written in Rust. The direct competitor to Claude Code and Gemini CLI.
• Codex IDE extension — VS Code / Cursor sidebar with the same agent, sharing context with your editor.
• Codex cloud — tasks run in isolated cloud containers on OpenAI's infrastructure. You can fire off several tasks in parallel from your phone or browser and review the resulting PRs later. None of the other three tools shipped this as a first-class surface.
• Codex code review — enable it on a GitHub repo and mention @codex in a PR to get an autonomous review pass.

Project memory: AGENTS.md

Just as Claude Code reads CLAUDE.md and Gemini CLI reads GEMINI.md, Codex reads AGENTS.md — and this one is an open convention that other tools have adopted too. Codex merges instructions hierarchically: a global ~/.codex/AGENTS.md, then the repo root, then nested folders, with deeper files taking precedence — the same layered model you learned for CLAUDE.md in M03.

Installation follows the same pattern you used in M02 for the other tools. Codex offers an npm package and a Homebrew formula. On first launch it asks you to sign in — and here you face the same fork as Claude Code: subscription sign-in (use your ChatGPT plan, no per-token bills) or API key (pay per token, required for CI).

# WHAT: Install the Codex CLI globally via npm
# WHY:  Same install pattern as Claude Code and Gemini CLI (M02)
# GOTCHA: Codex's sandbox is strongest on macOS/Linux. On Windows,
#         running inside WSL gives you the full Linux sandbox;
#         native PowerShell works but with weaker isolation guarantees.
npm install -g @openai/codex

# WHAT: Start Codex — first run opens a browser to sign in
# WHY:  "Sign in with ChatGPT" uses your existing plan (Plus/Pro/Business)
#       with no separate API billing
codex

# WHAT: Check version and verify your environment
codex --version

# WHAT: Install the Codex CLI (npm or Homebrew — pick one)
# WHY:  npm matches the other CLIs in this course; brew auto-updates
# GOTCHA: If npm -g fails with EACCES, use nvm instead of sudo
npm install -g @openai/codex
# or:
brew install codex

# WHAT: Start Codex — first run triggers the ChatGPT OAuth flow
# WHY:  Subscription auth = no per-token bills; API key = usage billing
codex

# WHAT: Verify the install
codex --version

config.toml — Codex's settings file

Claude Code uses JSON (.claude/settings.json); Codex uses TOML, stored at ~/.codex/config.toml. The three keys that matter most are the model, the sandbox mode, and the approval policy — the last two are explained in depth in Section 4.

# WHAT: The three keys you will actually touch
# WHY:  Everything else has sensible defaults
# GOTCHA: TOML, not JSON — no braces, no quoted keys

model = "gpt-5.3-codex"          # default agent model (2026)
sandbox_mode = "workspace-write" # what Codex CAN do (Section 4)
approval_policy = "on-request"   # when Codex must ASK (Section 4)

# WHAT: Let Codex write outside the repo in specific places only
# WHY:  workspace-write blocks everything outside the working dir by default
[sandbox_workspace_write]
writable_roots = ["/tmp/scratch"]

# WHAT: Wire up an MCP server — same protocol you learned in M07
# WHY:  Codex is an MCP client; servers configured here appear as tools
# GOTCHA: Claude Code puts this in JSON; Codex uses a TOML table
[mcp_servers.postgres]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-postgres"]
env = { DATABASE_URL = "postgresql://localhost/dev" }

AGENTS.md — your CLAUDE.md knowledge, transplanted

# Project: order-tracking-api

## Build & test
- Install: `npm ci`
- Test: `npm test` — ALWAYS run before declaring a task done
- Lint: `npm run lint -- --fix`

## Conventions
- TypeScript strict mode; no `any` without a comment justifying it
- All API handlers must validate input with zod before touching the DB
- Error responses follow RFC 7807 (problem+json)

## Boundaries
- Never edit `migrations/` — generate new migrations instead
- Secrets live in env vars only; flag any hardcoded credential you find

This is the most genuinely different thing about Codex, and the part worth slowing down for. Claude Code's permission system asks one question: "may I run this?" Codex splits security into two independent layers:

• Layer 1 — Sandbox mode — what Codex can technically do, enforced by the operating system. Even a confused or manipulated model cannot write outside the sandbox.
• Layer 2 — Approval policy — when Codex must stop and ask you before acting, even for things the sandbox would allow.

The three sandbox modes

• read-only — Codex can read files and answer questions but cannot edit or execute anything that changes state. The "explore a new codebase" mode.
• workspace-write — the everyday default. Codex can read, edit, and run commands inside the working directory; anything outside (other folders, the network) requires escalation and your approval.
• danger-full-access — no OS sandbox at all. The name is the documentation. Use only inside an already-isolated environment such as a disposable container.

The default Auto preset combines workspace-write with an on-request approval policy: Codex works autonomously inside the repo and interrupts you only when it wants to leave the workspace or reach the network. Compare that with Claude Code's default behavior of prompting per-tool-category, or Gemini CLI's plan-then-execute flow from M06 — three different answers to the same trust question.

In M08 you built GitHub Actions pipelines with claude -p and gemini in headless mode. Codex's equivalent is codex exec: it runs one task non-interactively and exits, which makes it scriptable in any pipeline.

# WHAT: Run a one-shot, non-interactive Codex task
# WHY:  No TUI, no prompts — suitable for scripts and CI
# GOTCHA: In CI there is no human to approve escalations, so the task
#         must fit inside the sandbox you grant it up front
codex exec "Run the test suite; if any test fails, fix the code (not the test) and re-run until green"

# WHAT: Same, but with explicit sandbox + JSON output for parsing
codex exec --sandbox workspace-write --json \
  "Summarize the diff between HEAD and main as release notes" \
  > release-notes.json || {
    echo "codex exec failed — check auth and rate limits" >&2
    exit 1
  }

# WHAT: Minimal PR-review job using Codex in headless mode
# WHY:  Mirrors the M08 pattern you built for Claude Code and Gemini CLI
# GOTCHA: CI requires API-key auth (OPENAI_API_KEY secret) —
#         your ChatGPT subscription login does not work headless in CI
name: codex-pr-review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - run: npm install -g @openai/codex
      - name: Review the diff
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        run: |
          codex exec --sandbox read-only \
            "Review the diff between origin/main and HEAD for bugs,
             security issues, and missing error handling.
             Output a markdown review." > review.md \
          || { echo "review failed" >&2; exit 1; }
      - name: Post review comment
        uses: marocchino/sticky-pull-request-comment@v2
        with: { path: review.md }

The two surfaces the other tools don't match

• Codex cloud — kick off tasks ("fix issue #142", "add tests for the parser") that run in parallel, isolated cloud containers, each producing a reviewable PR. It turns the agent from a pair-programmer into a small queue of background workers. The honest caveat: cloud containers don't have your local environment, so tasks needing unusual system dependencies are better run locally.
• GitHub code review — once enabled for a repo, commenting @codex review on any PR triggers an autonomous review. This overlaps with what you built manually in M08 — a build-vs-buy question: the hand-rolled pipeline is customizable and model-agnostic; the built-in reviewer is zero-maintenance.

Codex pricing flows through your ChatGPT plan, and in April 2026 OpenAI switched Codex from per-message limits to credit-based billing — your monthly allowance is consumed in proportion to actual token usage, so one giant refactor can cost as much as dozens of small Q&A tasks.

The model lineup

The default agent model in mid-2026 is GPT-5.3-Codex — a variant tuned specifically for long-horizon coding work rather than chat. Lighter tasks can run on the cheaper GPT-5.4-mini, and Pro subscribers get research-preview variants early. The strategic note: OpenAI versions its Codex models on a separate track from its chat models, exactly as Anthropic tunes Claude models for agentic coding — both vendors now treat "coding agent" as a distinct model category, which tells you where the investment is going.

M10's core lesson was that the tools compete for jobs, not loyalty. Codex competes almost entirely for one job — the autonomous-agent slot — which until now defaulted to Claude Code. Honest guidance, in the spirit of "this is not a ranking":

The bake-off protocol: the capstone asked you to build the same app with three tools. Extend it: take the same spec, run it through codex with the Auto preset, and score it on the same rubric — time to working code, correctness, error handling, and how often you had to intervene. One evening of measurement on your codebase beats any benchmark chart, including the ones in this course.