Picking a model (gpt-5-codex, gpt-5.5) and model_reasoning_effort
Using profiles (-p, --profile) for per-project model/sandbox bundles
Configuring MCP servers in [mcp_servers.*] blocks
Running headless: codex exec "...", JSON output, CI integration
Using codex app-server (v0.130+) for app-server / IPC integration
Writing custom prompts/commands in .codex/prompts/<name>.md
Disambiguating from the deprecated 2021 Codex completion model (code-davinci-002) — it's discontinued
Migrating between Codex CLI, Claude Code, and OpenCode
Do not use this skill when
Task is Claude Code CLI (settings.json, hooks, .claude/skills) — use claude-code
Task is OpenCode CLI (multi-provider, opencode.json) — use opencode
Task is the OpenAI Assistants/Responses API or SDK calls from code — use openai-sdk
Task is GitHub Copilot CLI (Microsoft's tool, different binary) — clarify with the user; this is a NAMING COLLISION
Task is the deprecated code-davinci-002 Codex completion model from 2021–2023 — refuse and redirect to this skill (modern Codex agent) or openai-sdk
Task is general agent benchmarking — use agent-evaluation
Purpose
The OpenAI Codex CLI (@openai/codex, github.com/openai/codex) is OpenAI's official agentic terminal tool, written predominantly in Rust (94.9% as of mid-2026). It's the OpenAI counterpart to Anthropic's Claude Code: heavy investment, fast release cadence (700+ releases since launch), Apache-2.0 license, 75K+ GitHub stars. It powers a coding agent backed by gpt-5-codex and related OpenAI models.
Critical naming clarification: "Codex" in 2026 means this agentic CLI tool. The original 2021-era Codex completion model (code-davinci-002, sunset 2023) is discontinued — do not write code targeting it. The modern Codex is fundamentally different: it's an agent CLI that uses current GPT-5 models under the hood.
This skill covers: install/auth, config.toml schema, sandbox + approval policy model (Codex's strongest area — Rust-enforced filesystem and network boundaries), MCP server configuration, headless codex exec, custom prompts, codex app-server for IPC, and migration to/from Claude Code and OpenCode.
Capabilities
Installation, auth, models
Three install paths: npm i -g @openai/codex (wraps the platform binary), brew install --cask codex (macOS app + CLI), or codex-aarch64-apple-darwin.tar.gz/codex-x86_64-unknown-linux-musl.tar.gz from GitHub Releases. Auth: codex login (ChatGPT subscription OAuth) or OPENAI_API_KEY env. Subscription path uses your ChatGPT quota; API path bills per token. Default model gpt-5-codex; gpt-5.5 for near-instant interactive use.
workspace-write: writes only within cwd and --add-dir
danger-full-access: no filesystem boundary (DFA)
Four approval policies:
untrusted: prompt for every tool call
on-request: prompt only when the model asks for elevation
on-failure: prompt only on command-failure / sandboxed error retry
never: no prompts (CI mode)
Productive unattended (CI / lane):approval_policy=never +
sandbox_mode=workspace-write. Interactive productive: -a on-request -s workspace-write.
/permissions switches live in interactive mode.
Fast mode (ChatGPT credits):service_tier="fast" + features.fast_mode=true
(~1.5× speed, ~2.5× credits on GPT-5.6). Lane stack: adoc Fast mode → lane-session.
Codex has no first-class named subagents. Closest equivalent: profiles + spawning codex exec -p review ... from a session. See references/subagents.md.
MCP servers
Configure in config.toml under [mcp_servers.<name>]:
codex exec "<prompt>" is one-shot mode (add --json for structured output). codex app-server (v0.130+) starts a headless IPC server for pipeline embedding. AGENTS.md is shared with OpenCode; slash command set differs from Claude Code. See references/interop.md and references/migration.md.
Behavioral Traits
Starts in read-only + untrusted for unfamiliar repos; loosens once trust is established
Unattended: approval never + workspace-write (never legacy --full-auto)
NEVER uses --dangerously-bypass-approvals-and-sandbox outside Docker/VM
Prefers profiles (-p lane-writer, -p night-review) over inline flags for lanes
Lane models: luna+max daytime write, terra onboard/docs, sol+high review/recovery
Uses codex exec review for branch review when available
Wraps long codex exec in lane-bg/lane-exec (Claude Bash FG ~2m)
Disambiguates the modern Codex CLI from the deprecated 2021 model whenever a user says "Codex" ambiguously
Verifies which surface (CLI vs VS Code extension vs macOS app) the user is on — they share config but expose settings differently
Stores secrets as ${ENV_VAR} interpolation in config.toml, never inline
Important Constraints
NEVER recommend the deprecated code-davinci-002 Codex completion model — it's discontinued; today's Codex is an agent CLI
NEVER use --dangerously-bypass-approvals-and-sandbox on a host machine — Docker/VM only
NEVER commit .codex/auth.json — it contains tokens; gitignore the .codex/ directory or specific auth files
NEVER conflate OpenAI Codex CLI with GitHub Copilot CLI — different products, different vendors (despite OpenAI being upstream to both)
NEVER hand-edit mcp_servers blocks for sensitive servers without codex mcp add validation
ALWAYS pin a profile per CI workflow (codex exec -p ci-review ...) instead of stacking flags
ALWAYS start unfamiliar repos in -s read-only -a untrusted mode
ALWAYS check codex --version after codex update — features depend on version (e.g., app-server requires 0.130+)
Related Skills
90%-filter applied. ✓ = active; rest are cascade markers.
