Codex Orange Paper: A Complete Hands-On Guide from Installation to Real-World Projects

This is not a product review. It’s a practical walkthrough based on real project experience.

Before We Start

This article is distilled from an unofficial open‑source guide to Codex. I’ve stripped out the fluff and kept only what actually helps you get work done.

It’s written for two groups of people:

  • Complete beginners who have never used an AI coding tool but want to start – you’ve probably heard that ChatGPT can write code, but you don’t know how to bring it into your real project.
  • Experienced users who have already used Cursor, Claude Code, or ChatGPT and want to understand what makes Codex different, and whether it’s worth switching.

We’ll cover four parts:

  1. What Codex actually is, and how it differs from ChatGPT, Cursor, and Claude Code
  2. Installation, setup, and which entry point fits your workflow
  3. The core features that truly matter in daily work
  4. A complete workflow – from taking over a new project to shipping code

This article is based on publicly available information as of June 22, 2026. Always check the official documentation and your own account for the latest changes.

Part 1: Understanding Codex – It’s Not “ChatGPT That Writes Code”

A Quick History of AI Coding Tools

If you think of Codex as just another AI that generates code, you’ll miss the real shift.

To see what changed, look at how AI coding tools evolved over the past few years:

  • 2021 – Copilot / Completion era – AI autocompleted your code. You wrote the start, it filled the rest. It was like a smarter input method – faster typing, but you still handled architecture, file discovery, testing, and debugging.

  • 2022 – ChatGPT / Conversation era – You could ask about errors, optimisations, and project structure. But the AI was not inside your project – you copied code, pasted errors, manually added context, then brought the answer back.

  • 2023–2024 – Cursor / Project‑collaboration era – AI entered the editor. It could see files, modify functions, refactor across files, and handle part of the development work. Still, it mostly stayed inside the IDE – you had to watch every change, decide the next step, run tests, and prepare commits.

  • 2025 onwards – Codex / Engineering Agent era – Codex is no longer just a completion model. It is an agent built for real software engineering tasks. It reads projects, explains code, fixes bugs, adds features, writes tests, refactors modules, runs commands, checks diffs, and prepares PR descriptions.

In short: the role of AI shifted from “code input method” to “conversation partner”, then to “pair programmer”, and now to “engineering agent”. The focus moved from writing code to delivering tasks.

What Codex Can Actually Do

Codex is not good at generating code from thin air. It is good at executing a set of engineering tasks inside a real project.

It can:

  • Read the project, find files, understand context, make a plan, modify code, run commands, check results, and present a reviewable diff.
  • Help you understand a new codebase – tech stack, entry points, core modules, build commands, and files you should not touch.
  • Explain functions, components, data flow, and potential risks – invaluable when inheriting legacy code.
  • Fix reproducible bugs, add small features (settings page, form validation, export button), and optimise frontend pages.
  • Write unit tests, edge‑case tests, extract duplication, split long functions, and refactor without changing public APIs.
  • Generate README, setup instructions, API docs, PR descriptions, commit messages, and changelogs.
  • Run tests, linters, type checks, builds, git status, and diffs – verifying results, not just guessing.

When NOT to Use Codex Directly

Avoid giving Codex unsupervised access to:

  • Production databases
  • Real user data
  • Payment or security‑critical logic
  • Large‑scale architectural migrations
  • Unbacked projects
  • Critical business logic without tests
  • Anything you cannot verify yourself

If you can’t judge whether the result is correct, do not let Codex work independently.

How Codex Compares to ChatGPT, Cursor, and Claude Code

Codex vs ChatGPT
ChatGPT is a consultant – you ask, it answers, you execute. Codex is an intern – you delegate tasks, it executes them. Use ChatGPT to think through the problem, then use Codex to carry out the solution inside your project.

Codex vs Cursor
Cursor is an AI‑powered editor – it stays inside your IDE and helps you write code interactively. Codex is an engineering agent – it runs tasks across your project, from planning to diff review. They are complementary, not substitutes.

Codex vs Claude Code
Both are agentic coding tools, but with different emphasis. Claude Code is a long‑term terminal companion – good for deep, multi‑step conversations inside your project. Codex is more of a multi‑endpoint task executor – it works across CLI, App, IDE, and Web, and integrates with OpenAI’s ecosystem, including ChatGPT accounts, GitHub workflows, and Skills. Choose based on your preferred workflow, model performance, pricing, and team habits.

Part 2: Installation, Configuration, and Environment Setup

Account Preparation

You need a ChatGPT account with a plan that includes Codex. Plan names, quotas, and features change – refer to the official page and your account dashboard.

Four Entry Points – Pick the One That Fits

Entry Point Best For
Codex App (Desktop) Beginners, graphical interface, parallel tasks, diff management, thread switching – supports macOS and Windows. Highly recommended for first‑time users.
Codex CLI Developers comfortable with the terminal, real project directories, automation, and combining with Git and build commands – supports macOS, Windows, and Linux.
Codex IDE Extension VS Code, Cursor, or Windsurf users – edit while seeing code, perfect for frontend work and local refactoring.
Codex Web Cloud‑based, GitHub‑connected tasks – ideal for remote execution, team collaboration, and PR workflows.

Start with the App for local practice, then gradually adopt CLI, IDE, and Web as you become comfortable with Git and team workflows.

Prerequisite Tools

Before installing Codex, have these ready:

  • Git (for change tracking, diff, and rollback)
  • VS Code or Cursor (for viewing and editing code)
  • Terminal (PowerShell on Windows, Terminal on macOS)
  • A modern browser
  • Node.js (for web, frontend, Next.js, Vite projects)
  • Python (for scripts and automation)
  • A GitHub account (if you plan to use Codex Cloud or push code)

Project Directory Setup

Codex needs a specific project folder to work on. Create a dedicated practice directory, e.g. ~/AI-Codex-Projects or D:\AI-Codex-Projects, with subfolders like hello-web, landing-page-demo, etc. Do not start with your most important production project.

Security and Permissions

Codex can read, modify, and run commands inside your project. Remember:

  • Use a test project first.
  • Never hard‑code passwords or API keys – use .env and avoid committing them.
  • Always commit to Git before a session – easy rollback.
  • Review every command Codex wants to run – ask it to explain if unsure.
  • Restrict it to the project folder, not your entire drive.

Installing and Getting Started with Codex App (Recommended)

macOS – Check your chip: Apple menu → About This Mac. If it says Apple M1/M2/M3/M4, download the Apple Silicon version; if Intel Core, download the Intel version. Drag Codex into Applications.

Windows – Go to the Codex App page, choose Windows – it redirects to Microsoft Store. Click “Get” or “Install”.

First Launch – After login, choose a project directory. For your first run, pick an empty practice folder. Codex will now treat that folder as its workspace.

Understanding the Interface

  • Project list – each entry is a local folder or Git repository, not a chat history list.
  • Thread – a task‑specific conversation inside a project. Keep one clear task per thread (e.g., “build homepage”, “fix button bug”, “improve mobile layout”).
  • Task window – where you type instructions and see Codex’s plan, execution, and summary.
  • Review pane – shows exactly which files changed, what was added or removed. Always check this – do not rely only on the text summary.
  • Diff – green = new lines, red = deleted lines. Always inspect the diff before accepting any change.

First‑run workflow – Login → choose practice folder → start a thread → type a simple task → wait for Codex to finish → open review pane → examine diff → continue or rollback.

A good first task: “Create a simple webpage with a black background, white text saying ‘Hello, Codex’ centred both horizontally and vertically, using only HTML and CSS.”

Installing and Getting Started with Codex CLI

macOS – Requires Node.js. Run npm install -g @openai/codex, then verify with codex --version. Alternatively, use Homebrew: brew install --cask codex.

Windows – Install Node.js, then open PowerShell and run npm install -g @openai/codex. Verify with codex --version. Never run Codex in system directories like C:\, Desktop, or Downloads – create a practice folder like D:\AI-Codex-Projects\hello-codex.

First Run – Type codex – it will prompt you to log in. You have two options:

  • ChatGPT account login (recommended for beginners) – browser opens, sign in, token returns to terminal.
  • API Key login (for developers, automation, CI/CD) – set OPENAI_API_KEY environment variable and run codex login --with-api-key.

Essential CLI Commands

Command Purpose
codex Start CLI
codex --version Verify installation
codex login Log in with ChatGPT
codex login status Check login state
codex logout Log out
codex doctor Diagnose environment issues
codex resume --last Resume the most recent session
codex archive Archive a finished thread
codex update Update CLI
codex exec "task" Run a one‑off task without interactive session

Slash Commands (inside Codex) – These are typed in the Codex prompt, not in your terminal:

Command What it does
/diff Show current changes
/plan Make a plan before executing
/permissions Adjust approval settings
/model Switch model / reasoning strength
/status Show current model, permissions, context
/init Generate AGENTS.md (project rules)
/compact Compress a long conversation
/quit Exit Codex

Start with these – they cover 80% of daily use.

Codex IDE Extension

Install directly in VS Code, Cursor, or Windsurf: Extensions → search “Codex” → install → restart → click the Codex icon in the sidebar → log in → open your project folder.

It can read the current file, selected code, modify files, run commands, fix errors, generate docs, switch models, and control permissions – all inside your editor.

Codex Web

The web interface at chatgpt.com/codex connects to your GitHub repositories. Codex runs in the cloud – no need to keep your local machine on.

Typical flow: open the page → log in with ChatGPT → connect GitHub → select a repository → choose a branch → describe the task → wait for cloud execution → review diff and results → create a Pull Request.

Use this for GitHub‑hosted projects, team PR workflows, or when you don’t want to occupy your local machine.

Part 3: Core Features Deep Dive

Automation

Automation lets Codex run scheduled checks – like a virtual on‑call engineer. You can set it to review recent sessions, summarise recurring issues, and propose reusable rules.

Example prompt: “Review the last week of Codex conversation logs and produce a summary of common mistakes, effective fixes, and personal preferences for UI, workflows, and interaction principles.”

Plugins

Plugins are add‑on capability packs. They connect Codex to external tools, browser automation, or specialised tasks.

Common plugins:

  • Chrome – browser control for testing
  • GitHub – repository management, issue handling
  • Computer Use – operates your desktop apps (high privilege)
  • Build Web Apps – generate frontend apps from descriptions
  • Figma – turn designs into code
  • Documents / Presentations / Spreadsheets – generate docs, slides, analyse data
  • HyperFrames / Remotion – create videos from code

Skill – Fixed Workflows for Recurring Tasks

A Skill is a packaged procedure. If you often ask Codex to “write a README” or “review UI”, turn that into a Skill – it includes instructions, resources, templates, and optional scripts.

When to create a Skill – when you repeat the same task often, when you want consistent output, or when your team shares a standard process.

A simple Skill structure includes: name, description, workflow steps, output format, and constraints.

Create one with the built‑in assistant: start a thread and type $skill-creator. It will ask you about the purpose, triggers, workflow, and output format, then generate the Skill file for you.

Use a Skill by mentioning its name, e.g., $readme-skill generate README.

MCP – Connecting External Tools

MCP (Model Context Protocol) is the interface that lets Codex talk to external services – databases, documentation, design tools, project management, internal APIs.

Think of Codex as the worker, MCP as the socket, MCP Server as the toolbox, and Tools as the individual implements.

Set up MCP via codex mcp add (CLI) or through the App’s Settings panel. After adding, just describe the task – Codex will use the MCP tool if it fits.

Git and GitHub Workflow

Git is your local version control; GitHub is remote collaboration; Codex is the agent that reads, modifies, and verifies.

Why Git is essential with Codex – you can see exactly what changed, rollback mistakes, recover deleted code, save safe checkpoints, and isolate experiments with branches or worktrees.

Basic flow: git init → commit a clean state → create a branch for Codex → let Codex work → review diff → run tests → commit if good → push → create PR.

Memory System – AGENTS.md

AGENTS.md is a project‑specific instruction file for Codex (similar to README for humans). It tells Codex:

  • Project tech stack and commands
  • Code style and directory structure
  • Which files are off‑limits
  • Required workflow before modifying code
  • Testing and commit requirements

Place it in the project root to affect the whole project, or in subdirectories for module‑specific rules. You can also have a user‑wide ~/.codex/AGENTS.md for personal preferences.

Part 4: The Standard Workflow – From Requirement to Delivery

Many beginners just type “build me a website” – and often end up with unverifiable changes. A stable workflow prevents that.

The Six‑Step Method

1. Requirement Breakdown – Before any code is written, define:

  • Background: why are we doing this?
  • Specific problem: what exactly needs to change?
  • Likely files: which files might be involved?
  • Boundaries: what must not be touched?
  • Acceptance criteria: what does “done” look like?
  • Tests: how will we verify?
  • Risks: what could break?

2. Planning – Ask Codex for a plan first. Use /plan or explicitly say “do not write code yet – give me a plan”. Review and approve before execution.

3. Small‑Step Implementation – Change one small piece at a time. After each step, check the result. Prevent Codex from refactoring unrelated code or adding unnecessary dependencies.

4. Testing – After each step, run:

  • Unit tests (if any)
  • Type checks
  • Linters
  • Build
  • Manual UI testing
  • Console and network checks
  • Regression tests (make sure old features still work)

5. Code Review – Two passes:

  • Codex self‑review: check if it modified only planned files, added no new deps, deleted no necessary logic, and handled edge cases.
  • Human review: inspect diff for file scope, deletions, naming consistency, business logic correctness, and security (tokens, auth, input validation).

6. Commit and Retrospective – After review:

  • Write a clear commit message (e.g., feat: add user profile page)
  • Prepare PR description: what changed, why, test results, risks, what to review
  • Log issues encountered and how they were solved
  • Summarise effective prompts and consider adding them to AGENTS.md
  • Update project documentation if needed

Ready‑to‑Use Templates

Read a new project – ask Codex for a project understanding report: tech stack, directory structure, start commands, test commands, core modules, and modification risks.

Fix a bug – describe the symptom, steps to reproduce, expected vs actual behaviour, relevant files – ask Codex to locate the cause and propose a fix before modifying.

Add a feature – describe the feature, entry point, interaction, visual requirements, data source, and acceptance criteria – get an implementation plan first.

Build a frontend page – specify purpose, audience, style, functionality, and done criteria.

Code review – ask Codex to review for potential bugs, edge cases, security, type issues, performance, unrelated modifications, and test coverage.

Refactor – provide the module path, goals (readability, reduce duplication, preserve behaviour, no API changes, no new deps) – require a plan and verification strategy.

Write tests – describe the function, boundaries, and edge cases – require coverage of normal, exceptional, and boundary paths.

Write documentation – generate README, setup guide, environment variables, common commands, directory structure, and FAQs – no fabrication – verify against the actual project.

Part 5: Real‑World Case Studies

All cases are based on a fictional “Pet Treats” e‑commerce project.

Case 1 – Build a Frontend Sales Page from Scratch

Create a local folder Pet-treats, open it in Codex App, enable plan mode, let Codex propose a structure (HTML/CSS), execute, preview in browser, initialise Git, use inline comments to tweak details (e.g., add monthly sales count), commit, push to GitHub, and deploy via GitHub Pages.

Case 2 – Add Login, Categories, and Cart

Add a login/registration page, create product categories with sub‑categories, use plan mode to confirm the approach, refine with comments, and add address confirmation before checkout.

Case 3 – Build an Admin Dashboard

Again, start with a plan – verify Codex’s understanding before any code.

Case 4 – Generate a Brand Pitch Deck

Install a PPT Skill from a GitHub repo, invoke it with $ppt-skill, and let Codex generate a complete presentation.

Case 5 – Create a Promo Video

Install the HyperFrames Skill, plan the video structure, and Codex produces a short product video.

Appendix: Third‑Party Model Integration (Unofficial)

This section covers a non‑official approach – using CC Switch to route Codex to third‑party models like DeepSeek. It is not an OpenAI feature.

CC Switch is an open‑source desktop tool that manages provider switching, MCP servers, and Skills across multiple agents (Claude Code, Codex, Gemini CLI) via a visual panel.

Steps:

  1. Download CC Switch from ccswitch.io
  2. Create an API key from your third‑party provider (e.g., DeepSeek)
  3. Open CC Switch, add a model, paste the API key
  4. Enable local routing mapping
  5. Turn on all routes in settings
  6. Enable the connection

If compatible, Codex may then be able to use that third‑model through this unofficial route. Use only in test repositories first – model capability, context length, tool‑call compatibility, pricing, and privacy depend on the third‑party service and your configuration.

Final Thoughts

This article condenses the core of the Codex Orange Paper. AI coding tools evolve fast – some details here may become outdated within months. But two things remain constant: the engineering mindset (understand before you change, iterate small, verify everything) and the underlying goal – freeing developers to focus on what to build, not how to type it.

If you’re just starting, grab Codex App, open a simple HTML project, and spend two hours going through the complete workflow. That hands‑on session will teach you more than reading a dozen more guides.