Codex

Checked against Codex CLI 0.157.1

Verified on 26 September 2026 with codex --help, codex exec --help and codex review --help. GPT-6 Astra has been the bundled default model since CLI 0.153.4; the server can override it for signed-in accounts. If a flag below is missing, run codex --version and check the 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 Astra. 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 covers every surface, including JetBrains and Xcode. For model choice and prices, see the models hub.

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):

   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:

   codex review --uncommitted

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

Copy-paste prompt: plan before any edit

/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

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).

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).

• 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:

  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.

• A human signs off on the evidence bundle, not every line (why evidence beats 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 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).

Where to go next with Codex

• Developers: installation, the desktop app guide and cost management.
• Tech leads: team workflows, enterprise governance and the tech lead track.
• Lifecycle and other tools: the AI-native SDLC, the tool map, Codex vs Cursor and Claude Code.