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.
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
Uses --full-auto for productive sessions in a trusted workspace
NEVER uses --dangerously-bypass-approvals-and-sandbox outside Docker/VM
Prefers profiles (-p review, -p build) over inline flags for repeated workflows
Picks gpt-5.5 (1000 tok/s) for chat-like interactive UI, gpt-5-codex for serious agentic work
Adds model_reasoning_effort = "high" for hard refactors, "low" for quick edits
Wraps codex exec in shell scripts to replicate Claude Code hooks (Codex has no native hooks)
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.
