# Codex quick start: from install to a verified first task

URL: https://developertoolkit.ai/en/codex/quick-start/
Description: The Codex quick start for developers: pick a surface, install, sign in, configure, and ship a first task you verify with tests and a review pass.

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.

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](/en/codex/quick-start/installation/)**: desktop app, CLI, or IDE extension.

2. **[Sign in](/en/codex/quick-start/authentication/)** with a ChatGPT plan or an API key.

3. **[Configure `config.toml`](/en/codex/quick-start/configuration/)**: model, approvals, sandbox.

4. **[Run your first task](/en/codex/quick-start/first-task/)**: a small task with acceptance criteria and test output.

5. **[Write `AGENTS.md`](/en/codex/quick-start/agents-md/)** with your build and test commands.

6. **[Connect GitHub](/en/codex/quick-start/github-integration/)** for cloud tasks and `@codex review`.

7. **[Review Codex's changes](/en/codex/quick-start/review-workflow/)**: `codex review`, `/review`, and `@codex review`.

8. **[Add an MCP server](/en/codex/quick-start/mcp-setup/)** with `codex mcp add` or `config.toml`.

9. **[Recover from errors](/en/codex/quick-start/error-recovery/)**: 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:

```bash
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.1 Sol (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](/en/ecosystem/models/).

## 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](/en/ladder/evidence-not-diffs/).

**Copy-paste prompt: orient Codex in a new repository**

```text
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**

```text
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](/en/codex/quick-start/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](/en/codex/quick-start/configuration/). Never `--dangerously-bypass-approvals-and-sandbox` outside a disposable, network-restricted sandbox |
| A cloud task misses your local setup | Cloud reads only the repository | Configure the [cloud environment](/en/codex/automate/cloud-environments/) |

More cases are in [error recovery](/en/codex/quick-start/error-recovery/).

## Where to go after the Codex quick start

- [CLI commands](/en/codex/build/cli-commands/) and [non-interactive runs](/en/codex/automate/non-interactive/).
- [Permissions and sandboxes](/en/workflows/harness/permissions-and-sandboxing/) before unattended runs.
- Other tools: [Claude Code quick start](/en/claude-code/quick-start/) and [Cursor quick start](/en/cursor-ide/quick-start/).
- [Install Codex](/en/codex/quick-start/installation/) — Set up the desktop app, CLI, and IDE extension