This guide shows how to get started with ChatGPT‑5 Codex, what each surface (Cloud, CLI, IDE) is for, and how to work with it effectively—using Prompt‑Driven Development (SDD), TDD, and ADR/PR guardrails.
1) What ChatGPT‑5 Codex is (in one minute)
Codex is OpenAI’s coding agent. It can read your repo, modify files, run code in a sandbox, and work on multiple tasks in parallel. In ChatGPT, you delegate work to Codex; it can also run via a CLI or inside your IDE. Codex uses GPT‑5 (or GPT‑5‑Codex) as its default model for coding/agentic tasks.
Key capabilities
- Reads/edits entire codebases; proposes/opens PRs with tests and docs.
- Runs jobs in the cloud sandbox (Codex Cloud) or in your terminal (Codex CLI).
- Pairs neatly with the OpenAI Agents SDK patterns (tools, sessions, handoffs).
2) Prerequisites & access
- ChatGPT plan with GPT‑5/Codex access.
- Enable Codex (Cloud/CLI/IDE) and authenticate.
- Optional GitHub connection so Codex can open PRs.
3) Pick your surface: Cloud vs CLI vs IDE
| Surface | Best for | How to use |
|---|---|---|
| Codex Cloud | Parallel, long‑running, repo‑wide changes; tests/docs generation | In ChatGPT, assign tasks; Codex returns diffs/logs/PRs |
| Codex CLI | Local, repo‑scoped edits; fast feedback | Install CLI, point at a dir, delegate tasks from terminal |
| IDE Extension | Interactive editing and previews inside your editor | Install extension, sign in; apply multi‑file diffs and open PRs |
You can hand work off between ChatGPT (cloud) and your local environment.
4) First‑time setup (10–15 minutes)
- Turn on Codex in your ChatGPT plan; enable Cloud/CLI/IDE.
- Install the CLI; authenticate; run
codex --help. - Connect GitHub so Codex can push branches and open PRs.
- Verify GPT‑5 / GPT‑5‑Codex is selected for coding tasks.
5) Core workflows (copy‑paste playbooks)
A) Read & explain a codebase
Prompt: “Scan this repo. Produce a 1‑page map of modules, public interfaces, and runtime flows. List top 5 risks and missing tests. Output markdown.”
B) Add a feature with SDD × TDD (tests first)
- Architect: micro‑spec, constraints, API, G/W/T tests, risks, ADR draft.
- Red: add failing unit + contract tests.
- Green: minimal change to pass specific tests.
- Refactor: internal cleanup; tests stay green.
- PR + ADR: open PR with summary, link ADR, include curl/screenshots and rollout.
C) Large‑scale refactor (use Codex Cloud)
Prompt: “Branch refactor/config-split. Move config to app/config.py with typed settings, add tests, update docs. Open a PR with risks and rollback.”
D) Bug hunt with reproduction
Prompt: “For issue #142, create a failing test that reproduces the crash, implement the minimal fix, add a regression test, and open a PR with root‑cause notes.”
6) Model choices & tuning
- GPT‑5 = default recommendation for Codex tasks.
- GPT‑5‑Codex = further‑optimized for complex, real‑world engineering (if available, prefer this).
7) Patterns that keep Codex effective (and safe)
- Small, explicit prompts → small diffs. Ask for “minimal change to pass test X.”
- Always pair with tests. Use TDD: tests first, then minimal implementation.
- Record decisions. Have Codex draft an ADR for significant changes and link it in the PR.
- Use Agents SDK concepts for agentic apps (tools, sessions, handoffs).
- Deterministic CI. Mock network calls; enforce “no green, no merge.”
8) When to use Cloud vs CLI vs IDE
- Cloud: broad, parallelizable, or long‑running work (scaffold, repo‑wide refactors, tests/docs).
- CLI: local, focused changes you’ll review immediately in git.
- IDE: interactive flow (discuss file, preview/apply diffs, open PRs).
Final advice
Treat Codex like a teammate who types fast: you set the spec, tests, and limits; it does the labor. Keep changes small, test‑guarded, and documented via ADRs—and use PRs as the gate. That’s how GPT‑5‑powered development stays fast and clean.