# Codex

URL: https://developertoolkit.ai/en/codex/
Description: OpenAI Codex for developers and tech leads: ship a first verified change, pick a sandbox and approval policy, prove the output, find the right guide.

**Checked against Codex CLI 0.157.1**

  Verified on 26 September 2026 with `codex --help`, `codex exec --help` and `codex review --help`. GPT-6.1 Sol has been the bundled default model since CLI 0.159.1 (2026-09-29, checked 2026-10-12; GPT-6 Astra before that); the server can override it for signed-in accounts. If a flag below is missing, run `codex --version` and check the [changelog](/en/codex/reference/changelog/).

Codex is OpenAI's coding agent: it reads a repository, runs commands inside a sandbox, edits files and reviews diffs from the CLI, a desktop app, IDE extensions and Codex cloud. Its bundled default model is GPT-6.1 Sol. The sandbox, the approval policy and the repository's own gates, not the model, decide whether its output can be trusted.

This hub serves developers adopting Codex and tech leads standardising it. A common starting point: Codex finishes the task, but a script still passes the removed `--full-auto` flag, `AGENTS.md` does not name the test command, and you read every diff to find out whether anything broke.

## What this Codex guide gives you

- A first change taken from a read-only plan to a reviewed diff.
- A permission setting for each kind of session, from planning to CI.
- A verification stack, so you sign off on evidence, not lines of code.

## Which Codex surface should you start on?

Local surfaces share `~/.codex/config.toml`, `AGENTS.md`, skills and MCP servers; Codex cloud has its own environments.

| Surface | Start it with | Reach for it when |
| --- | --- | --- |
| CLI (TUI) | `codex` in the repository root | You want plan mode, worktrees and every flag |
| Non-interactive CLI | `codex exec "…"` | Scripts and CI need JSONL events (`--json`) or schema-shaped output (`--output-schema`) |
| Desktop app | `codex app` (macOS and Windows) | Parallel threads, each in its own worktree |
| IDE extension | VS Code, Cursor and Windsurf (now Devin Desktop), per OpenAI's README | You want the agent beside the file you are editing |
| Codex cloud | chatgpt.com/codex, or `codex cloud` (experimental) | Long background tasks, or `@codex review` on a pull request |

[Installation](/en/codex/quick-start/installation/) covers every surface, including JetBrains and Xcode. For model choice and prices, see the [models hub](/en/ecosystem/models/).

## How do you ship a first verified change with Codex?

You need a Git repository with a clean working tree and a short spec committed at `docs/specs/login-rate-limit.md`.

1. Install Codex, sign in and check the installation (terminal):

   ```bash
   npm install -g @openai/codex
   codex login
   codex doctor
   ```

2. Start `codex` in the repository root, accept the trust prompt, and run `/init` to generate `AGENTS.md`. Edit it until it names the exact typecheck, lint and test commands.

3. Paste the planning prompt below (it starts with `/plan`) before the agent starts a turn, and approve the plan. Copy the approved plan into `docs/plans/login-rate-limit.md` yourself (plan mode edits no file), then commit it with `AGENTS.md`.

4. Start a session in a managed Git worktree with `codex --worktree` and paste the build prompt.

5. Check the reported commands and exit statuses, then review the diff from inside the worktree:

   ```bash
   codex review --uncommitted
   ```

   Open a pull request; required checks and a named reviewer gate it.

**Copy-paste prompt: plan before any edit**

```text
/plan Read AGENTS.md and docs/specs/login-rate-limit.md, then inspect the code that handles POST /api/login.
Propose an implementation plan: the files you will change, the tests you will write first,
the commands that prove the change (typecheck, lint, unit, integration), the risks, and how to roll back.
Do not edit any file.
```

**Copy-paste prompt: build one milestone and report evidence**

```text
Read docs/plans/login-rate-limit.md and AGENTS.md. Implement milestone 1 and nothing else.
Write the failing tests first, then the code. Run every typecheck, lint and test command AGENTS.md lists.
If a check fails, fix the implementation; never delete, skip or loosen a test.
Finish with: files changed, each command you ran with its exit status, and the risks you did not cover.
```

## Which sandbox and approval policy should a Codex session use?

Codex separates what a command may touch (the sandbox) from when it asks you first (the approval policy). In 0.157.1, `-a` accepts only `on-request` (the default) and `never`.

OpenAI prefers permission profiles (beta, CLI 0.138.0 or later), selected with `-c default_permissions="<profile>"` or in `config.toml`. The legacy `--sandbox` flag still works, but the two do not compose, so pick one per session ([configuration guide](/en/codex/quick-start/configuration/)).

| Session | Setting | Watch out for |
| --- | --- | --- |
| Planning and review | `/plan`; or profile `:read-only` (`-c default_permissions=":read-only"`), or legacy `--sandbox read-only` | Enter `/plan` before a turn, not mid-run |
| Interactive build in a worktree | Profile `:workspace` (`-c default_permissions=":workspace"`), or legacy `--sandbox workspace-write`, with `on-request` approvals | Approving without reading |
| Long unattended local run | `--approve-for-me` (a reviewer model approves inside `workspace-write`) | Judges sandbox escapes, not correctness |
| CI job | `codex exec -c default_permissions=":read-only"` (or legacy `--sandbox read-only`) for review; `:workspace` or `workspace-write` for fixes | `codex exec` already runs with approval `never` and has no `-a` |
| Full access | `--dangerously-bypass-approvals-and-sandbox` | Disposable, network-restricted runners only |

## How do you know Codex's output is right without reading every line?

Each layer enforces what the one above asks for:

- **`AGENTS.md` names the gates** but enforces nothing ([AGENTS.md for Codex](/en/codex/quick-start/agents-md/)).
- **Hooks and rules enforce.** Trusted hooks in `.codex/hooks.json` run whatever the prompt says; `.rules` files decide which commands may leave the sandbox.
- **`codex review` re-reads the diff** (`--uncommitted`, `--base` or `--commit`).
- **CI re-runs the gates**, and a read-only review adds a machine-readable second opinion:

  ```bash
  codex exec -c default_permissions=":read-only" \
    --output-schema .github/codex/schemas/findings.json \
    "Review the diff between origin/main and HEAD against docs/specs/login-rate-limit.md. Report only blocking findings, each with file, line, and the behaviour that fails."
  ```

  The findings schema is in [Codex in CI/CD](/en/codex/ship/ci-cd/#fail-the-build-on-p0-findings-with-structured-output).

- **A human signs off on the [evidence bundle](/en/workflows/ship/evidence-bundle/)**, not every line ([why evidence beats diffs](/en/ladder/evidence-not-diffs/)).

**Untrusted pull requests in CI**

Never run contributor code while a secret is in the environment. When a job that holds a secret reviews a contributor's pull request, run Codex from a checkout of your default branch, put the contributor's commit in a separate directory the agent only reads, load no `AGENTS.md`, hooks or project config from it, stay read-only, and never pass `--dangerously-bypass-hook-trust`. [Codex in CI/CD](/en/codex/ship/ci-cd/) shows the `openai/codex-action@v1` setup.

## What breaks first when you adopt Codex?

- **"unexpected argument".** 0.157.1 rejects `codex exec -a never …`. Drop the flag: `codex exec` already runs with approval `never`, and a `codex -a … exec` prefix does not change that.
- **Scripts pass `--full-auto`.** It is absent from 0.157.1. Use a permission profile (`-c default_permissions=":workspace"`), `--approve-for-me` or `--sandbox workspace-write`.
- **Codex ignores `AGENTS.md`.** Untrusted projects do not supply it (since CLI 0.150.0); trust the project, but only a checkout you or your team wrote, never a contributor's branch in CI.
- **Parallel sessions collide.** `codex --worktree` isolates files, not ports or databases ([worktrees](/en/codex/automate/worktrees/)).

## Where to go next with Codex

- **Developers:** [installation](/en/codex/quick-start/installation/), the [desktop app guide](/en/codex/build/app-mastery/) and [cost management](/en/codex/operate/cost-management/).
- **Tech leads:** [team workflows](/en/codex/team/team-workflows/), [enterprise governance](/en/codex/team/enterprise-governance/) and the [tech lead track](/en/start/tech-lead/).
- **Lifecycle and other tools:** the [AI-native SDLC](/en/method/lifecycle/), the [tool map](/en/method/lifecycle/tool-map/), [Codex vs Cursor and Claude Code](/en/comparison/vs-codex/).