Codex quick start: from install to a verified first task

The Codex quick start is a nine-guide path for developers that takes OpenAI’s coding agent from installation to a first merged change. It covers the four Codex surfaces (desktop app, CLI, IDE extension and cloud), sign-in, config.toml, AGENTS.md, GitHub, and MCP. The finish line is a task checked by tests and a second review pass.

Start on the wrong surface and the afternoon goes on setup. This page picks your first surface, orders the guides, and shows how to trust the first task without reading every line.

What you have at the end of the Codex quick start

• One surface installed, signed in, and passing codex doctor
• A config.toml and an AGENTS.md that you wrote on purpose
• A first task signed off on tests and a codex review pass
• A recovery move for each common setup failure

Which Codex surface should you start with?

All four surfaces run the same agent, differing in where work runs and how you review it.

Desktop app

The Codex desktop app runs on macOS and Windows; codex app launches it from the terminal. Its merger into the ChatGPT desktop app as a Codex mode on 2026-07-09 is reported second-hand (secondary: Neowin).

Start here if you prefer a graphical client to a terminal.

CLI

The open-source codex CLI runs on macOS, Linux, and Windows. It has an interactive terminal UI and codex exec for non-interactive runs in scripts and CI. For parallel tasks, opt a session into its own Git worktree with --worktree or /worktree (worktree support is on by default since 0.156.0).

Start here if you work mostly in the terminal or CI.

IDE extension

The OpenAI extension runs in VS Code and forks such as Cursor. JetBrains IDEs and Xcode have separate integrations (secondary: Neowin).

Start here if you want small tasks without leaving the editor.

Cloud

Codex cloud runs tasks in an environment built from your GitHub repository and returns a diff you can open as a pull request.

Start here if long tasks should run while your machine is off.

Note

The CLI reads config.toml and credentials from CODEX_HOME, default ~/.codex. Codex cloud ignores local files; configure its environments separately.

Follow the Codex quick-start path in order

Each guide assumes the previous one. Already installed? Start at step 3.

1. Install Codex: desktop app, CLI, or IDE extension.

2. Sign in with a ChatGPT plan or an API key.

3. Configure config.toml: model, approvals, sandbox.

4. Run your first task: a small task with acceptance criteria and test output.

5. Write AGENTS.md with your build and test commands.

6. Connect GitHub for cloud tasks and @codex review.

7. Review Codex’s changes: codex review, /review, and @codex review.

8. Add an MCP server with codex mcp add or config.toml.

9. Recover from errors: symptoms, causes, and recovery prompts.

What you need before you start

• A ChatGPT plan that includes Codex (OpenAI’s README lists Plus, Pro, Business, Edu, and Enterprise) or an OpenAI API key with billing enabled.
• Git, and a real repository with a test command: a demo gives you nothing to verify.
• Node.js 16 or later only if you install the CLI through npm (@openai/codex 0.157.1 declares node >=16). The standalone installer and Homebrew need no Node.js.

After steps 1 and 2, confirm the setup in your terminal:

codex --version        # codex-cli 0.157.1 on 2026-09-26
codex login status     # which account or API key is active
codex doctor           # installation, config, auth, and runtime checks

Codex starts on its bundled default model, GPT-6 Astra (the server can override it for signed-in accounts); check which model is active in the session status before you tune anything. Tune reasoning effort before switching models. Current models and prices live on the models hub.

How to check the first task without reading every line

Treat the first task as a test of your setup. Ask for evidence up front:

1. The task states acceptance criteria before any code changes.
2. Codex runs the project’s own tests and lint, and reports the commands and results.
3. You rerun those commands yourself: a green run you did not see is a claim.
4. A second pass reviews the diff: codex review --uncommitted in the terminal, or /review in the terminal UI.
5. CI runs on the pull request. You read only what tests, review, and CI flag.

Why this works: evidence, not diffs.

Copy-paste prompt: orient Codex in a new repository

Before changing anything, map this repository for me. Read the README,
the package or build manifest, and the CI workflow. Report:
1. The exact commands to install, build, run tests, and lint, and
   whether each one passes right now (run them).
2. The five directories that matter most and what each owns.
3. Anything in CI that a local run would miss.
Then draft an AGENTS.md from what you found. Do not edit other files.

Copy-paste prompt: a first task that ships with its own evidence

Fix the failing test in the smallest module that has one. If nothing
fails, add a missing test for an untested branch in a utility function.
Before you edit, write 2-3 acceptance criteria as a checklist.
After you edit, run the full test suite and the linter, and paste the
commands and their final output. List every file you changed and why.
Stop and ask if the fix needs more than 50 changed lines.

What goes wrong in the first hour with Codex?

Symptom	Likely cause	Recovery
Usage bills to the API, or limits look wrong	Signed in with the wrong method (API key or ChatGPT plan)	Check codex login status; codex logout and sign in again
Codex ignores your AGENTS.md	Untrusted projects do not supply AGENTS.md (since CLI 0.150.0)	Trust the project when asked, then restart
The CLI ignores your settings	CODEX_HOME points somewhere other than the file you edited	Check CODEX_HOME; rerun codex doctor
codex -a on-failure or --full-auto fails	Both are invalid in CLI 0.157.1 (checked 2026-09-26)	Use -a on-request or -a never; for unattended runs see configuration
Tests fail only inside Codex	The sandbox blocks network or writes outside the workspace	Writes: --add-dir <DIR>. Network: approve the command, or grant network in configuration. Never --dangerously-bypass-approvals-and-sandbox outside an external sandbox
A cloud task misses your local setup	Cloud reads only the repository	Configure the cloud environment

More cases are in error recovery.

Where to go after the Codex quick start

• CLI commands and non-interactive runs.
• Permissions and sandboxes before unattended runs.
• Other tools: Claude Code quick start and Cursor quick start.

Install Codex Set up the desktop app, CLI, and IDE extension