Skip to main content

OpenAI Codex

Codex is OpenAI's coding agent. It reads your repository, proposes and applies edits, and runs commands inside a sandbox, with approval rules you control. It is available as a terminal CLI, an IDE extension, part of the ChatGPT desktop app, and as Codex cloud for delegated tasks.

This page covers installation and the basics. For the full deep-dive (AGENTS.md, sandbox and approvals, skills, subagents, hooks, MCP, codex exec, cloud), see the Codex section.

Installation​

Standalone installer (macOS and Linux):

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

npm or Homebrew also work:

npm install -g @openai/codex
# or
brew install --cask codex

Starting Codex​

Run it from inside your project directory:

codex

This opens an interactive terminal session. Codex reads the repository, makes edits, and runs commands as you iterate. You can also pass the first prompt directly:

codex "refactor the auth module to use dependency injection"

For scripts and CI, use non-interactive mode:

codex exec "run the test suite and summarize failures"

See Automation & Non-interactive Mode for output formats, exit handling, and CI patterns.

Authentication​

Run codex login (or just codex) and choose one of:

  • Sign in with ChatGPT: uses your ChatGPT plan (Free, Go, Plus, Pro, Business, Edu, or Enterprise). Codex cloud requires this method.
  • API key: usage-based billing through your OpenAI API organization.

The sign-in method also determines which admin controls and data-handling policies apply.

Surfaces​

SurfaceBest forNotes
CLI (codex)Terminal workflows, scripting, CIFull feature set: skills, subagents, hooks, MCP, codex exec
IDE extensionEditing with open files and selections as contextVS Code, Cursor, Windsurf; Xcode and JetBrains have their own Codex integrations
ChatGPT desktop appParallel chats, worktrees, long-running workmacOS, Windows, and Linux
Codex cloudDelegated tasks in isolated environments, PR reviewStarted from the web, CLI (codex cloud), or IDE; results applied locally

Key concepts​

Sandbox and approvals​

Codex runs commands inside an OS-level sandbox (Seatbelt on macOS, bubblewrap and seccomp on Linux, a native sandbox on Windows). Two settings control what it can do:

  • sandbox_mode: read-only, workspace-write, or danger-full-access
  • approval_policy: on-request (default), never, or a granular policy

Switch modes during a session with /permissions. Details: Permissions & Sandbox and Auto-review.

AGENTS.md​

Persistent project instructions live in AGENTS.md at the repository root (with optional nested files per directory and a personal ~/.codex/AGENTS.md). This is the equivalent of CLAUDE.md for Claude Code. Details: AGENTS.md & Memories.

Skills, subagents, hooks, plugins, MCP​

Codex has native support for:

  • Skills: SKILL.md folders in .agents/skills/ or ~/.agents/skills/, invoked explicitly or picked up automatically
  • Subagents: built-in and custom agents (.codex/agents/*.toml) that run focused work in their own context
  • Hooks: scripts or MCP tools that run at lifecycle events
  • Plugins: installable bundles of skills, MCP servers, and connectors
  • MCP: external tools via codex mcp add or config.toml

Models and effort​

Codex uses OpenAI models such as gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna, with /model to switch and adjustable reasoning effort:

codex --model gpt-5.6-terra

See Managing Context for effort levels, fast mode, and compaction.

Tips​

  • Start in read-only or the default workspace-write with on-request approvals until you trust how Codex interprets your instructions
  • Use specific, scoped prompts ("add input validation to the signup handler" rather than "improve the code")
  • Create Git checkpoints before and after a task so you can revert
  • Write an AGENTS.md before anything else; it is the highest-leverage configuration file

More: Tips.

Limitations​

  • Only OpenAI models (no Claude, Gemini, or open-source models) unless you configure a custom model_provider
  • Codex cloud requires ChatGPT sign-in; API-key users get local surfaces only
  • Some features are marked experimental in the official docs and can change between releases

Further reading​