Getting Started with Codex

You just got access to Codex. You opened the App, stared at the empty thread list, and wondered: do I type the same thing here as I would in ChatGPT? Where does the CLI fit in? What about the VS Code extension? And what is a “cloud thread” anyway?

The gap between “Codex is available” and “Codex is shipping code for me” is real. This quick-start section closes it.

What You’ll Walk Away With

• All four Codex surfaces installed and authenticated in under 15 minutes
• A config.toml tuned for your approval comfort level and preferred model
• An AGENTS.md that gives Codex real context about your project’s conventions
• At least one MCP server connected and working
• A GitHub repo connected for PR workflows and @codex mentions
• A completed end-to-end task: prompt, execution, review, and merge
• A mental model for when things fail and how to recover

The Four Surfaces at a Glance

Before diving in, understand what each surface is built for so you pick the right one at the right time.

App (macOS)

The native desktop app is your command center. It runs multiple threads in parallel, isolates changes in Git worktrees, has built-in diff review and commit tools, supports automations on a schedule, and sends notifications when background tasks finish. Think of it as your project manager for Codex work.

Best for: Running 3-5 parallel tasks, reviewing diffs, committing and pushing, automations, voice dictation.

CLI

The open-source CLI (codex command) is built in Rust and runs on macOS, Linux, and Windows. It provides an interactive TUI for conversational work and a non-interactive codex exec mode for scripting. Approval modes, image input, web search, and local code review are all built in.

Best for: Terminal-first workflows, scripting and piping, CI/CD integration, headless automation, remote/SSH sessions.

IDE Extension

The Codex extension for VS Code, Cursor, Windsurf, and JetBrains IDEs lives in your sidebar. It starts in Agent mode by default, reads files, runs commands, and writes changes in your project directory. You can delegate tasks to Cloud without leaving your editor.

Best for: Staying in your editor, using file context and @file references, quick inline tasks, cloud delegation.

Cloud

Codex Cloud runs at chatgpt.com/codex. It spins up an environment from your GitHub repo, executes tasks in the background, and produces a diff you can merge as a PR. You can also trigger it by mentioning @codex in GitHub issue or PR comments.

Best for: Long-running tasks, background work, PR-driven workflows, tasks when you are away from your machine.

The Quick-Start Path

This section walks through ten focused guides in the order you should follow them. Each builds on the previous one, but experienced developers can jump to any topic.

1. Installation — Install the App (macOS), CLI (npm or Homebrew), and IDE extension (VS Code Marketplace). Takes 5 minutes.

2. Authentication — Sign in with your ChatGPT subscription or configure an OpenAI API key. Understand the trade-offs between subscription and API billing.

3. Configuration — Set your default model, approval policy, sandbox mode, and web search preference in config.toml. Learn the precedence order across user, project, and CLI overrides.

4. AGENTS.md Setup — Write global and project-level AGENTS.md files that give Codex real context about your codebase conventions, test commands, and review guidelines.

5. MCP Setup — Connect your first MCP server (Context7 for docs, Playwright for browser testing, or GitHub for PR management). Configure via CLI or config.toml.

6. GitHub Integration — Connect a repo for Codex Cloud, enable @codex review on PRs, set up automatic reviews, and trigger cloud tasks from issue comments.

7. First Task — Run a real task across all four surfaces: ask Codex to find and fix a bug, add a feature, or refactor a module. See how each surface handles the same prompt differently.

8. Review Workflow — Review Codex’s changes using the App’s diff pane, inline comments, staging, and reverting. Understand scope toggles (uncommitted, branch, last turn) and partial staging.

9. Error Recovery — Handle sandbox permission failures, command timeouts, context overflow, wrong-direction edits, and network errors. Build recovery muscle memory.

Note

All four surfaces share the same ~/.codex/config.toml and AGENTS.md files. Configure once, use everywhere.

Prerequisites

Before starting, ensure you have:

• A ChatGPT subscription (Plus, Pro, Business, Edu, or Enterprise) or an OpenAI API key with credits
• Node.js 18+ installed (for CLI via npm) or Homebrew (for CLI via brew)
• macOS Apple Silicon (for the native App — CLI and IDE work on macOS, Linux, and Windows)
• VS Code, Cursor, or Windsurf (for the IDE extension)
• Git configured on your system
• A real project to work with — Codex is wasted on hello-world repos

Tip

Prompt to check your prerequisites:

Paste this into your terminal to verify Node.js, Git, and your shell are ready:

node --version && git --version && echo "Ready for Codex"

Choosing Your Primary Surface

You do not need to use all four surfaces. Most developers settle on one or two as their primary and use the others situationally.

Your workflow	Start with	Add later
Terminal-first, scripts and CI	CLI	Cloud for background tasks
IDE-centric, visual diffs	IDE Extension	App for parallel threads
Multi-task, parallel features	App	CLI for scripting
Remote team, async PR reviews	Cloud	IDE Extension for follow-ups

Pick the surface closest to how you already work, then expand as you find use cases for the others.

What’s Next

Start with installation. The entire quick-start section is designed to be completed in a single afternoon, with each guide taking 10-20 minutes.

Install Codex Set up the App, CLI, and IDE extension on your machine