Codex CLI: The Definitive Technical Reference

Codex operates as a multi-surface coding agent, not a chatbot that writes code. The CLI reads your codebase, executes commands in a sandbox, patches files, connects to external services via MCP, and delegates long-running tasks to the cloud. It runs locally but thinks globally — the same intelligence powers four distinct surfaces depending on how you work.

The difference between casual and effective Codex usage comes down to five core systems. Master these and Codex becomes a force multiplier:

1. Configuration system — controls behavior via config.toml
2. Sandbox & approval model — gates what Codex can do
3. AGENTS.md — defines project-level operating contracts
4. MCP protocol — extends capabilities to external services
5. Skills system — packages reusable domain expertise

I spent months running Codex alongside Claude Code across production codebases, CI/CD pipelines, and team workflows. This guide distills that experience into the comprehensive reference I wish existed when I started. Every feature includes actual syntax, real configuration examples, and the edge cases that trip up experienced users.

Stability note: Features marked [EXPERIMENTAL] are subject to change between releases. Codex Cloud and the MCP command group are both experimental as of v0.101.0. Core CLI, sandbox, AGENTS.md, config.toml, and Skills are stable.

Key Takeaways

• Four surfaces, one brain: CLI, desktop app, IDE extension, and cloud tasks all share the same GPT-5.x-Codex intelligence — pick the surface that fits your workflow.
• OS-level sandboxing: Codex enforces filesystem and network restrictions at the kernel level (Seatbelt on macOS, Landlock + seccomp on Linux), not inside containers.
• AGENTS.md is cross-tool: Your project instructions work in Codex, Cursor, Amp, Jules, Windsurf, and Cline — write once, use everywhere.
• Profiles save context-switching overhead: Define named config presets (fast, careful, auto) and switch between them with --profile.
• 272K input context fills fast: Use /compact, focused prompts, and @file references to manage token budgets proactively.

How Codex Works: The Mental Model

Before diving into features, understand how Codex’s architecture shapes everything you do with it. The system operates across four surfaces backed by a shared intelligence layer:

┌─────────────────────────────────────────────────────────┐
│                    CODEX SURFACES                        │
├─────────────────────────────────────────────────────────┤
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐ │
│  │   CLI    │  │ Desktop  │  │   IDE    │  │ Cloud  │ │
│  │ Terminal │  │   App    │  │Extension │  │  Tasks │ │
│  └──────────┘  └──────────┘  └──────────┘  └────────┘ │
│  Local exec     Multi-task    Editor-native  Async      │
│  + scripting    + worktrees   + inline edits detached   │
├─────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                         │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐   │
│  │   MCP   │  │ Skills  │  │  Apps   │  │  Search │   │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘   │
│  External tools, reusable expertise, ChatGPT            │
│  connectors, web search (cached + live)                  │
├─────────────────────────────────────────────────────────┤
│  SECURITY LAYER                                          │
│  ┌─────────────────────────────────────────────────┐    │
│  │    Sandbox (Seatbelt / Landlock / seccomp)      │    │
│  │    + Approval Policy (untrusted → never)        │    │
│  └─────────────────────────────────────────────────┘    │
│  OS-level filesystem + network restrictions              │
├─────────────────────────────────────────────────────────┤
│  CORE LAYER                                              │
│  ┌─────────────────────────────────────────────────┐    │
│  │         GPT-5.x-Codex Intelligence              │    │
│  │   Tools: Shell, Patch, Read, Web Search         │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens          │
└─────────────────────────────────────────────────────────┘

Core Layer: The GPT-5.x-Codex model family powers everything. As of v0.101.0, gpt-5.3-codex is the default model with a 272K-token input context window (128K output, 400K total budget).³⁵ It reads files, writes patches, executes shell commands, and reasons about your codebase. When context fills, Codex compacts the conversation to free space. This layer costs tokens.

Security Layer: Every command Codex runs passes through an OS-level sandbox. On macOS, Apple’s Seatbelt framework enforces kernel-level restrictions. On Linux, Landlock + seccomp filter filesystem and syscall access. The sandbox operates at the kernel level, not inside containers. The approval policy then decides when to ask for human confirmation.

Extension Layer: MCP connects external services (GitHub, Figma, Sentry). Skills package reusable workflows that Codex loads on demand. Apps connect to ChatGPT connectors. Web search adds real-time context from the internet.

Surface Layer: CLI for terminal power users and automation. Desktop app for multi-threaded project management. IDE extension for edit-compile-test loops. Cloud for async tasks that run independently.

The key insight: Most users only use one surface. Power users use all four — Cloud for long-running tasks, CLI for deterministic repo operations, IDE extension for tight coding loops, and the desktop app for planning and coordination.

Table of Contents

1. How Do I Install Codex?
2. Core Interaction Surfaces
3. Configuration System Deep Dive
4. Which Model Should I Choose?
5. Decision Frameworks
6. How Does the Sandbox & Approval System Work?
7. How Does AGENTS.md Work?
8. What Is MCP (Model Context Protocol)?
9. What Are Skills?
10. Plan Mode & Collaboration
11. Non-Interactive Mode (codex exec)
12. Codex Cloud & Background Tasks
13. The Codex Desktop App
14. GitHub Action & CI/CD
15. Codex SDK
16. What Does Codex Cost?
17. Performance Optimization
18. How Do I Debug Issues?
19. Enterprise Deployment
20. Community Tips & Techniques
21. Migration Guide
22. Quick Reference Card
23. Changelog
24. References

How Do I Install Codex?

Package Managers

# npm (recommended)
npm install -g @openai/codex

# Homebrew (macOS)
brew install --cask codex

# Upgrade to latest
npm install -g @openai/codex@latest

Binary Downloads

For environments without npm or Homebrew, download platform-specific binaries from GitHub Releases¹:

System Requirements

• macOS: Apple Silicon or Intel (full sandbox support via Seatbelt)
• Linux: x86_64 or arm64 (sandbox via Landlock + seccomp)
• Windows: Experimental (WSL recommended for full sandbox support)²

Authentication

codex login                  # Interactive OAuth (recommended)
codex login --device-auth    # OAuth device code flow (headless)
codex login --with-api-key   # API key from stdin
codex login status           # Check auth state (exit 0 = logged in)
codex logout                 # Clear stored credentials

Two authentication paths:

1. ChatGPT Account (recommended): Sign in with your existing Plus, Pro, Team, Business, Edu, or Enterprise subscription. Full feature access including cloud tasks.
2. API Key: Set via CODEX_API_KEY environment variable or codex login --with-api-key. Some features (cloud threads) may be unavailable.

Expert tip: Credential storage is configurable via cli_auth_credentials_store in config.toml. Options: file (default), keyring (OS keychain), or auto (keyring if available, file fallback).

Shell Completions

# Generate completions for your shell
codex completion bash > /etc/bash_completion.d/codex
codex completion zsh > ~/.zsh/completions/_codex
codex completion fish > ~/.config/fish/completions/codex.fish

Verify Installation

codex --version
# Codex CLI v0.101.0

Core Interaction Surfaces

Codex provides four distinct interfaces backed by the same intelligence. Each surface is optimized for a different workflow pattern.

1. Interactive CLI (Terminal UI)

codex                        # Launch TUI
codex "fix the failing tests" # Launch with initial prompt
codex -m gpt-5.3-codex      # Specify model
codex --full-auto            # Workspace-write sandbox + on-request approval

The terminal UI is a full-screen application with:

• Composer: Type prompts, attach files with @, run shell commands with ! prefix
• Output pane: Streaming model responses, tool calls, and command output
• Status bar: Model, token usage, git branch, sandbox mode

Key TUI shortcuts:

Slash commands available in the TUI:

2. Codex Desktop App (macOS)

codex app                    # Launch desktop app (auto-installs if missing)

The desktop app adds capabilities the CLI doesn’t have:

• Multi-tasking: Run multiple parallel agents across different projects simultaneously
• Git worktree isolation: Each thread works on an isolated copy of your repo
• Inline diff review: Stage, revert, and commit changes without leaving the app
• Integrated terminal: Per-thread terminal for running commands
• Conversation forking: Branch conversations to explore alternatives
• Floating pop-out windows: Detach conversations into portable windows
• Automations: Schedule recurring tasks (issue triage, CI monitoring, alert response)

When to use the app vs CLI: Use the desktop app when you’re coordinating multiple workstreams or need visual diff review. Use the CLI when you want terminal composability, scripting, or CI/CD integration.

3. IDE Extension (VS Code, Cursor, Windsurf)

The Codex IDE extension integrates directly into your editor:

• Agent mode by default: Reads files, makes edits, runs commands
• Inline edits: Context-aware suggestions in your active files
• Shared sessions: Sessions sync between CLI and IDE extension
• Same authentication: Sign in with ChatGPT account or API key

Install from the VS Code Marketplace or Cursor/Windsurf extension stores.³

4. Codex Cloud [EXPERIMENTAL]

Cloud tasks run asynchronously in OpenAI-managed environments:

• Fire and forget: Queue tasks that run independently of your local machine
• Parallel execution: Run multiple cloud tasks simultaneously
• PR creation: Codex creates pull requests from completed work
• Local apply: Pull cloud results into your local repo with codex apply <TASK_ID>

codex cloud list             # List recent cloud tasks
codex apply <TASK_ID>        # Apply diff from a specific cloud task

Cloud tasks are also accessible from chatgpt.com/codex.⁴

Configuration System Deep Dive

Codex uses TOML for configuration. Understanding the precedence hierarchy is critical — it determines which settings win when they conflict.

Precedence (Highest to Lowest)

1. Session overrides (highest): CLI flags (--model, --sandbox, --ask-for-approval, --search, --enable/--disable, --profile) and -c key=value overrides
2. Project config (.codex/config.toml, discovered from CWD upward to project root — closest directory wins)
3. User config ($CODEX_HOME/config.toml, defaults to ~/.codex/config.toml)
4. System config (/etc/codex/config.toml on Unix)
5. Built-in defaults (lowest)

requirements.toml acts as a policy constraint layer — it restricts what values users can select after normal config merging. See Enterprise Deployment.

Config File Locations

Expert tip: The CODEX_HOME environment variable overrides the default ~/.codex directory. Useful for CI/CD or multi-account setups.

Complete Configuration Reference

# ~/.codex/config.toml — annotated reference

# ─── Model Selection ───────────────────────────────────
model = "gpt-5.3-codex"                # Default model (272K input context)
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_reasoning_effort = "medium"       # low|medium|high|xhigh (model-dependent)
model_reasoning_summary = "auto"        # auto|concise|detailed|none
model_verbosity = "medium"              # low|medium|high
personality = "pragmatic"               # none|friendly|pragmatic
review_model = "gpt-5.2-codex"         # Model for /review command
oss_provider = "lmstudio"              # lmstudio|ollama (used with --oss)

# ─── Sandbox & Approval ───────────────────────────────
sandbox_mode = "workspace-write"        # read-only|workspace-write|danger-full-access
approval_policy = "on-request"          # untrusted|on-failure|on-request|never

[sandbox_workspace_write]
writable_roots = []                     # Additional writable paths
network_access = false                  # Allow outbound network
exclude_tmpdir_env_var = false          # Exclude $TMPDIR from sandbox
exclude_slash_tmp = false               # Exclude /tmp from sandbox

# ─── Web Search ────────────────────────────────────────
web_search = "live"                     # Web search mode (constrained by allowed modes)

# ─── Instructions ──────────────────────────────────────
developer_instructions = ""             # Additional injected instructions
model_instructions_file = ""            # Custom instructions file path
compact_prompt = ""                     # Custom history compaction prompt

# ─── Shell Environment ─────────────────────────────────
[shell_environment_policy]
inherit = "all"                         # all|core|none
ignore_default_excludes = false         # Set true to keep KEY/SECRET/TOKEN vars
exclude = []                            # Glob patterns to exclude
set = {}                                # Explicit overrides
include_only = []                       # Whitelist patterns

# ─── Authentication ────────────────────────────────────
cli_auth_credentials_store = "file"     # file|keyring|auto
forced_login_method = "chatgpt"         # chatgpt|api

# ─── History & Storage ─────────────────────────────────
[history]
persistence = "save-all"                # save-all|none
max_bytes = 0                           # Cap size (0 = unlimited)

tool_output_token_limit = 10000         # Max tokens per tool output
log_dir = ""                            # Custom log directory

# ─── UI & Display ──────────────────────────────────────
file_opener = "vscode"                  # vscode|vscode-insiders|windsurf|cursor|none
hide_agent_reasoning = false
show_raw_agent_reasoning = false
check_for_update_on_startup = true

[tui]
notifications = false                   # Enable notifications
notification_method = "auto"            # auto|osc9|bel
animations = true
show_tooltips = true
alternate_screen = "auto"               # auto|always|never
status_line = ["model", "context-remaining", "git-branch"]

# ─── Project Trust ─────────────────────────────────────
project_doc_max_bytes = 32768           # Max AGENTS.md size (32 KiB)
project_doc_fallback_filenames = []     # Alternative instruction filenames
project_root_markers = [".git"]         # Project root detection

# ─── Feature Flags ─────────────────────────────────────
# Use `codex features list` for current names/stages/defaults.
[features]
shell_tool = true                       # Shell command execution (stable)
collaboration_modes = true              # Plan mode (stable)
personality = true                      # Personality selection (stable)
request_rule = true                     # Smart approvals (stable)
unified_exec = true                     # PTY-backed exec (stable)
shell_snapshot = true                   # Shell env snapshots (stable)
remote_models = true                    # Refresh remote model list (stable)
apps = false                            # ChatGPT Apps/connectors (experimental)
child_agents_md = false                 # AGENTS.md guidance (experimental)
runtime_metrics = false                 # Runtime summary in turns

# ─── Project Trust ─────────────────────────────────────
[projects."/absolute/path/to/repo"]
trust_level = "trusted"                 # Per-project trust override

Profiles

Named configuration presets for different work modes:

# Define profiles in ~/.codex/config.toml

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
personality = "pragmatic"

[profiles.careful]
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.auto]
model = "gpt-5.3-codex"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"

Activate a profile:

codex --profile fast "quick refactor"
codex --profile careful "security audit"
codex -p auto "fix CI"

Expert tip: Set a default profile with profile = "fast" at the top level of your config. Override per-session with --profile.

Custom Model Providers

Connect to Azure, local models, or proxy services:

[model_providers.azure]
name = "Azure OpenAI"
base_url = "https://YOUR_PROJECT.openai.azure.com/openai"
wire_api = "responses"
query_params = { api-version = "2025-04-01-preview" }
env_key = "AZURE_OPENAI_API_KEY"

[model_providers.ollama]
name = "Ollama (Local)"
base_url = "http://localhost:11434/v1"
wire_api = "chat"

Use local models with the --oss flag:

codex --oss "explain this function"               # Uses default OSS provider
codex --oss --local-provider lmstudio "explain"   # Explicit LM Studio
codex --oss --local-provider ollama "explain"      # Explicit Ollama

Or set in config:

model_provider = "oss"
oss_provider = "lmstudio"   # or "ollama"

Inline Config Overrides

Override any config value from the command line:

codex -c model="gpt-5.2-codex" "refactor the API"
codex -c 'sandbox_workspace_write.network_access=true' "install dependencies"
codex -c model_reasoning_effort="xhigh" "debug the race condition"

Which Model Should I Choose?

Available Models (February 2026)

The exact model list varies by account and rollout. Check your local cache: ~/.codex/models_cache.json.

Model Selection Flowchart

Is this a quick fix or simple question?
├─ Yes → gpt-5.1-codex-mini (fastest, cheapest)
└─ No
   ├─ Do you need real-time pairing speed?
   │  ├─ Yes → gpt-5.3-codex-spark (interactive, lower latency)
   │  └─ No
   │     ├─ Is this a multi-file refactor or migration?
   │     │  ├─ Yes → gpt-5.2-codex (272K context, strong at long tasks)
   │     │  └─ No → gpt-5.3-codex (default, best overall)
   └─ Still unsure? → gpt-5.3-codex

Reasoning Effort

Control how much the model “thinks” before responding:

Supported levels are model-dependent. Not all models support every level.

codex -c model_reasoning_effort="xhigh" "find the race condition"

Expert tip: xhigh reasoning can use 3-5x more tokens than medium for the same prompt. Reserve it for genuinely hard problems where the extra thinking pays off.

Model Switching

Switch models mid-session with the /model slash command, or set per-run via --model / -m:

codex -m gpt-5.3-codex-spark "pair with me on this component"

Decision Frameworks

When to Use Each Surface

When to Use Each Sandbox Mode

When to Use Each Reasoning Level

How Does the Sandbox & Approval System Work?

Codex uses a two-layer security model that separates what is technically possible from when human approval is required. This is fundamentally different from Claude Code’s permission system — Codex enforces restrictions at the OS kernel level.⁵

Layer 1: Sandbox (What Is Possible)

The sandbox controls filesystem and network access using OS-native mechanisms:

Platform-specific enforcement:

• macOS: Apple’s Seatbelt framework via sandbox-exec with mode-specific profiles compiled at runtime and enforced by the kernel⁶
• Linux: Landlock for filesystem restrictions + seccomp for syscall filtering. A standalone helper process (codex-linux-sandbox) provides defense-in-depth isolation. Optional Bubblewrap (bwrap) pipeline available as an alternative⁷
• Windows: Experimental native sandbox with restricted tokens. WSL recommended for full sandbox support (inherits Linux Landlock + seccomp)

Why this matters: Unlike container-based sandboxing (Docker), OS-level sandboxing is faster, lighter, and harder to escape. The kernel enforces restrictions before Codex even sees the system call.

Layer 2: Approval Policy (When To Ask)

The approval policy determines when Codex pauses to ask for human confirmation:

The --full-auto Flag

--full-auto is a convenience alias for:

codex --sandbox workspace-write --ask-for-approval on-request

Critical gotcha: --full-auto overrides any explicit --sandbox value. If you pass --full-auto --sandbox read-only, you get workspace-write because --full-auto takes precedence.⁸

Recommended Configurations

Daily development (safe default):

sandbox_mode = "workspace-write"
approval_policy = "on-request"

Power user (full access, human-in-the-loop):

sandbox_mode = "danger-full-access"
approval_policy = "untrusted"

This is the community-recommended “sweet spot” — maximum capability but approval required for every command.⁹

CI/CD automation:

sandbox_mode = "workspace-write"
approval_policy = "never"

Enabling Network Access

Network is blocked by default in workspace-write mode. Enable it when needed:

# Per-run
codex -c 'sandbox_workspace_write.network_access=true' "install the packages"

# In config.toml
[sandbox_workspace_write]
network_access = true
writable_roots = ["/path/to/extra/dir"]   # Additional writable directories
exclude_slash_tmp = false                  # Prevent /tmp from being writable
exclude_tmpdir_env_var = false             # Prevent $TMPDIR from being writable

Testing the Sandbox

Verify sandbox behavior before trusting it:

codex sandbox macos --full-auto -- ls /etc/passwd   # macOS test
codex sandbox linux --full-auto -- cat /etc/shadow   # Linux test

How Does AGENTS.md Work?

AGENTS.md is Codex’s project instruction system — an open standard¹⁰ supported by Codex, Cursor, Amp, Jules (Google), Windsurf, Cline, Factory, and a growing list of AI coding tools. It defines how Codex should behave within a specific repository or directory.

Discovery Hierarchy

Codex builds an instruction chain at session start by walking the directory tree:

1. Global (~/.codex/): AGENTS.override.md > AGENTS.md
2. Project (git root to current directory): Each level checked for AGENTS.override.md > AGENTS.md > fallback filenames
3. Merging: Files concatenate root-down; closer files appear later in the prompt and override earlier guidance

~/.codex/AGENTS.md                     ← Global defaults
  └─ /repo/AGENTS.md                   ← Project-wide rules
      └─ /repo/services/AGENTS.md      ← Service-specific rules
          └─ /repo/services/payments/
               AGENTS.override.md      ← Overrides everything above for this dir

What Makes a Great AGENTS.md

Based on direct guidance from Codex itself and community patterns¹¹:

DO: - Be specific: "Use rg --files for discovery" beats "search efficiently" - Define closure: What does “done” mean? (tests pass, lint clean, etc.) - Include commands: Build, test, lint, format — exact invocations - Organize by task: Coding, review, release, incident/debug sections - Define escalation: What to do when blocked or encountering unexpected state

DON’T: - Dump entire style guides without execution rules - Use ambiguous directives (“be careful,” “optimize”) - Mix contradictory priorities (speed + exhaustive verification + no runtime budget) - Write prose documentation — AGENTS.md is operational policy, not README

Example: Production AGENTS.md

# Repository Guidelines

## Build, Test, and Development Commands
- Run API (dev): `python3 -m uvicorn main:app --reload`
- Install deps: `pip install -r requirements.txt`
- Lint: `python3 -m ruff check .` (auto-fix: `--fix`)
- Format: `python3 -m ruff format .`
- Tests: `python3 -m pytest -v`
- Coverage: `python3 -m pytest --cov=app --cov-report=term-missing`

## Coding Style & Naming Conventions
- Python 3.11+. Type hints on all functions.
- Ruff enforced: 88-char lines, double quotes, spaces for indent.
- Naming: modules `snake_case.py`, classes `PascalCase`, functions `snake_case`.

## Commit & Pull Request Guidelines
- Conventional Commits: `feat:`, `fix:`, `docs:`, `refactor:`, `chore:`, `test:`
- Commits should be small and focused.
- PRs must include: description, test plan, and screenshots for UI changes.

## Security
- Never commit secrets. Use `.env` for local config.
- Validate all external API calls with proper error handling.

The Override Mechanism

AGENTS.override.md at any directory level replaces the normal AGENTS.md for that scope. Use for:

• Release freezes: “No new features, fixes only”
• Incident mode: “All changes must be reviewed by on-call”
• Temporary hardening: “No dependency updates this sprint”

Configuration

# Custom fallback filenames (in addition to AGENTS.md)
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]

# Increase max size for large instruction files
project_doc_max_bytes = 65536    # 64 KiB (default: 32 KiB)

Scaffold Generation

codex                           # Launch TUI
/init                           # Generate AGENTS.md scaffold

Or verify your instruction chain:

codex --ask-for-approval never "Summarize your current instructions"

What Is MCP (Model Context Protocol)? [experimental]

MCP extends Codex’s capabilities by connecting to external tools and services. The codex mcp command group is currently marked experimental — commands and config format may change between releases. Codex supports two transport types: STDIO (local processes) and Streamable HTTP (remote servers).¹²

Configuring MCP Servers

STDIO servers (local processes):

# In ~/.codex/config.toml or .codex/config.toml

[mcp_servers.context7]
enabled = true
required = true                         # Fail startup if unavailable
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env = { "MY_VAR" = "value" }            # Static env vars
env_vars = ["PATH", "HOME"]             # Forward host env vars
cwd = "/path/to/project"                # Optional working directory
startup_timeout_sec = 10
tool_timeout_sec = 60
enabled_tools = ["search", "summarize"]  # Tool allowlist
disabled_tools = ["slow-tool"]           # Tool denylist

HTTP servers (remote):

[mcp_servers.figma]
enabled = true
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }
env_http_headers = { "X-Org-Id" = "FIGMA_ORG_ID" }  # Headers from env vars
startup_timeout_sec = 10
tool_timeout_sec = 60

CLI Management

codex mcp add context7 -- npx -y @upstash/context7-mcp
codex mcp add context7 --env API_KEY=... -- npx -y @upstash/context7-mcp   # With env vars
codex mcp add figma --url https://mcp.figma.com/mcp --bearer-token-env-var FIGMA_OAUTH_TOKEN
codex mcp list                          # List all configured servers
codex mcp list --json                   # JSON output
codex mcp get context7                  # Show server config
codex mcp get context7 --json           # JSON output
codex mcp login <server>                # OAuth flow for HTTP servers
codex mcp logout <server>               # Remove OAuth credentials
codex mcp remove <server>               # Delete server definition

In-session: /mcp shows active servers and available tools.

Running Codex AS an MCP Server

Codex can expose itself as an MCP server for multi-agent orchestration:¹³

codex mcp-server                        # Start as MCP server (stdio transport)

This exposes two tools: 1. codex(): Start a new session with prompt, sandbox, model, and approval parameters 2. codex-reply(): Continue an existing session with threadId and prompt

Use with the Agents SDK (Python):

from agents import Agent, Runner
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Codex CLI",
    params={"command": "npx", "args": ["-y", "codex", "mcp-server"]},
    client_session_timeout_seconds=360000,
) as codex_mcp_server:
    agent = Agent(name="Developer", mcp_servers=[codex_mcp_server])
    result = await Runner.run(agent, "Fix the failing tests")

Notable MCP Servers

What Are Skills?

Skills are reusable, task-specific capability packages that Codex loads on demand. They follow the open agent skills standard.¹⁴

Skill Structure

my-skill/
  SKILL.md           (required — instructions)
  scripts/           (optional — executable scripts)
  references/        (optional — reference docs)
  assets/            (optional — images, icons)
  agents/openai.yaml (optional — metadata, UI, dependencies)

Discovery Locations

User-installed skills are managed in $CODEX_HOME/skills (default: ~/.codex/skills), including built-in system skills under .system/. Codex supports symlinked skill folders.

Creating a Skill

SKILL.md format:

---
name: security-audit
description: Run a comprehensive security audit on the codebase.
---

## Security Audit Procedure

1. Scan for hardcoded secrets using `rg -i "(api_key|password|secret|token)\s*=" --type py`
2. Check for SQL injection: look for string interpolation in queries
3. Verify input validation on all API endpoints
4. Check dependency vulnerabilities: `pip audit` or `npm audit`
5. Review authentication and authorization patterns
6. Report findings with severity levels (Critical/High/Medium/Low)

Metadata (agents/openai.yaml):

interface:
  display_name: "Security Audit"
  short_description: "Comprehensive codebase security review"
  icon_small: "./assets/shield.svg"
  brand_color: "#DC2626"
  default_prompt: "Run a security audit on this repository"

policy:
  allow_implicit_invocation: false    # Require explicit $skill

dependencies:
  tools:
    - type: "mcp"
      value: "snyk"
      transport: "streamable_http"
      url: "https://mcp.snyk.io/mcp"

Invoking Skills

• Explicit: /skills menu or $skill-name mention in prompt
• Implicit: Codex auto-detects matching skills from task description (if allow_implicit_invocation: true)
• Creator: Use $skill-creator to interactively build a new skill
• Installer: Use $skill-installer install <name> to install community skills

Enable/Disable

[[skills.config]]
path = "/path/to/skill/SKILL.md"
enabled = false

Plan Mode & Collaboration

Plan mode lets Codex design an approach before executing changes. It’s enabled by default (since v0.94.0).¹⁵

Entering Plan Mode

/plan                              # Switch to plan mode
/plan "redesign the API layer"     # Plan mode with initial prompt

In plan mode, Codex: - Reads files and analyzes the codebase - Proposes an implementation plan - Does not make changes until you approve - Streams the plan in a dedicated TUI view

Steer Mode

Steer mode (enabled by default since v0.98.0) allows you to inject new instructions while Codex is working:

• Enter: Sends instructions immediately during a running turn
• Tab: Queues a follow-up for after the current turn completes

Steer mode enables real-time course correction without stopping the agent.

Conversation Forking

Fork conversations to explore alternatives without losing your current progress:

/fork                              # Fork current conversation
/fork "try a different approach"   # Fork with new prompt

Forks create independent threads — changes in one fork don’t affect the other.

Non-Interactive Mode (codex exec)

codex exec runs Codex non-interactively for scripting, CI/CD, and automation.¹⁶

Basic Usage

codex exec "summarize the repository structure"
codex exec --full-auto "fix the CI failure"
codex exec --json "triage open bugs" -o result.txt

By default, codex exec writes progress/events to stderr and the final agent message to stdout. This makes it composable with standard Unix pipelines.

JSON Lines Output

With --json, stdout becomes a JSONL event stream:

codex exec --json "fix the tests" | jq

Event types: thread.started, turn.started/completed/failed, item.started/completed, error

{"type":"thread.started","thread_id":"019c5c94-..."}
{"type":"turn.started"}
{"type":"item.started","item":{"id":"item_1","type":"command_execution","status":"in_progress"}}
{"type":"item.completed","item":{"id":"item_3","type":"agent_message","text":"..."}}
{"type":"turn.completed","usage":{"input_tokens":24763,"cached_input_tokens":24448,"output_tokens":122}}

Structured Output

Enforce response shape with JSON Schema:

codex exec "Extract project metadata" \
  --output-schema ./schema.json \
  -o ./project-metadata.json

-o / --output-last-message writes the final message to a file.

Session Resume and Review

codex exec resume --last "continue where you left off"
codex exec resume <SESSION_ID> "fix the remaining issues"
codex exec review --base main           # Code review against a branch

Key Flags

CI Authentication

codex exec supports CODEX_API_KEY for non-interactive authentication in automation environments.

Codex Cloud & Background Tasks [EXPERIMENTAL]

Status: Codex Cloud is an experimental feature. Interfaces, pricing, and availability may change. Cloud environments are managed by OpenAI — you do not control the infrastructure.

Codex Cloud runs tasks asynchronously in OpenAI-managed environments.⁴

How It Works

1. Submit a task (via chatgpt.com/codex, Slack integration, or CLI)
2. Codex clones your repo into an isolated cloud sandbox
3. The agent works independently — reads code, runs tests, makes changes
4. When done, Codex creates a PR or provides a diff for review
5. Apply results locally with codex apply <TASK_ID>

Internet Access in Cloud

Agent internet is off by default and configured per environment:

• Off: No agent internet access (default)
• On: Optional domain allowlist + HTTP method restrictions

Allowed domains: pypi.org, npmjs.com, github.com
Allowed methods: GET, HEAD, OPTIONS

Setup scripts can still use internet to install dependencies, even when agent internet is off.

Slack Integration

Mention @Codex in a Slack channel or thread to start a cloud task.

Prerequisites: 1. Eligible ChatGPT plan (Plus, Pro, Business, Enterprise, or Edu) 2. Connected GitHub account 3. At least one configured cloud environment 4. Slack app installed for your workspace

Codex replies with a task link and posts results when complete.

Cloud CLI

codex cloud exec --env <ENV_ID> "Fix failing tests"  # Start a cloud task
codex cloud status <TASK_ID>                          # Check task progress
codex cloud diff <TASK_ID>                            # View task diff
codex cloud list                                      # List recent tasks
codex cloud list --json                               # JSON output
codex cloud apply <TASK_ID>                           # Apply from cloud subcommand
codex apply <TASK_ID>                                 # Apply diff (top-level shortcut)

The Codex Desktop App

The Codex desktop app (macOS only, Apple Silicon) provides a graphical interface optimized for multi-project management.¹⁷

Installation

codex app                      # Auto-downloads and installs on first run

Or download directly: Codex.dmg

Key Features

Automations

Automations run locally in the app — the app must be running and the project available on disk:

• In Git repos, automations use dedicated background worktrees
• In non-Git projects, runs execute directly in the project directory
• Automations use your default sandbox settings

Example use cases: - Issue triage: Automatically categorize and prioritize new issues - CI monitoring: Watch build failures and suggest fixes - Alert response: React to monitoring alerts with diagnostic analysis - Dependency updates: Check for and apply security patches

Results appear in a review queue for human approval.

Windows Support

Windows alpha testing opened in February 2026. Sign up at openai.com for early access.¹⁸

GitHub Action & CI/CD

The official GitHub Action integrates Codex into your CI/CD pipeline.¹⁹

Basic Usage

# .github/workflows/codex.yml
name: Codex
on:
  pull_request:
    types: [opened]

jobs:
  codex:
    runs-on: ubuntu-latest
    outputs:
      final_message: ${{ steps.run_codex.outputs.final-message }}
    steps:
      - uses: actions/checkout@v5
      - name: Run Codex
        id: run_codex
        uses: openai/codex-action@v1
        with:
          openai-api-key: ${{ secrets.OPENAI_API_KEY }}
          prompt-file: .github/codex/prompts/review.md
          sandbox: workspace-write
          safety-strategy: drop-sudo

Configuration Options

Output: final-message — final Codex response text for downstream steps/jobs.

Safety Strategies

Access Controls

with:
  allow-users: "admin,maintainer"     # Limit who can trigger
  allow-bots: false                   # Block bot-triggered runs

Default: Only collaborators with write access can trigger Codex workflows.

Codex SDK

The TypeScript SDK embeds Codex’s agent capabilities into custom applications.²⁰

Installation

npm install @openai/codex-sdk

Basic Usage

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();

// Multi-turn conversation
const turn1 = await thread.run("Diagnose CI failures and propose a fix");
console.log(turn1.finalResponse);

const turn2 = await thread.run("Implement the fix and add tests");
console.log(turn2.items);

// Resume a previous session
const resumed = codex.resumeThread("<thread-id>");
await resumed.run("Continue from previous work");

Advanced SDK Features

• runStreamed(...): Async event stream for intermediate updates
• outputSchema: Enforce JSON-shaped final output
• Multimodal input: Pass text + local images ({ type: "local_image", path: "..." })

Thread and Client Configuration

// Custom working directory, skip git check
const thread = codex.startThread({
  workingDirectory: "/path/to/project",
  skipGitRepoCheck: true,
});

// Custom environment and config overrides
const codex = new Codex({
  env: { CODEX_API_KEY: process.env.MY_KEY },
  config: { model: "gpt-5.2-codex" },
});

Sessions persist under ~/.codex/sessions.

Runtime: Node.js 18+.

What Does Codex Cost?

Access via ChatGPT Plans

Codex availability depends on your ChatGPT plan and organization settings:

Plan limits and throughput are subject to change. Check current entitlements in ChatGPT and your admin settings.

API Billing

When using Codex through the API, usage is billed per token under standard OpenAI API pricing for the selected model (plus any applicable prompt-caching discounts). Check the official API pricing page for current rates.

Cost Optimization Strategies

1. Use profiles: Create a fast profile with gpt-5.1-codex-mini and model_reasoning_effort = "low" for routine tasks
2. Reserve high reasoning: Only use xhigh for genuinely hard problems — it costs 3-5x more tokens
3. Use --ephemeral: Skip session persistence in CI/CD to reduce overhead
4. Minimize reasoning summaries: Set model_reasoning_summary = "none" when you don’t need explanations
5. Batch with exec mode: codex exec avoids TUI overhead for automation workflows
6. Monitor usage: Check /status in the TUI and your org billing dashboards

Performance Optimization

Context Management

The flagship models have 272K-token input windows (128K output, 400K total budget), but they still fill faster than you think. Manage proactively:

1. Use /compact regularly: Summarizes conversation history to free tokens
2. Provide local docs: High-quality AGENTS.md and local documentation reduce exploration overhead (which consumes context)
3. Use @ to attach specific files: Reference files directly instead of asking Codex to find them
4. Keep prompts focused: Scoped prompts with exact files consume less context than open-ended exploration

Token Efficiency

Speed Optimization

1. gpt-5.3-codex-spark: Lower-latency variant for interactive pairing
2. --profile fast: Pre-configured mini model with low reasoning
3. Parallel tool execution: Codex runs independent reads/checks concurrently — structure prompts to enable this
4. Outcome-driven loops: Ask for “implement, test, fix, stop when green” instead of step-by-step instructions

How Do I Debug Issues?

Common Problems and Solutions

Diagnostic Tools

codex --version                        # Check CLI version
codex login status                     # Verify authentication
codex mcp list                         # Check MCP server status
codex debug app-server --help          # Debug app server issues

In-session TUI diagnostics:

/status                                # Token/session overview
/config                                # Inspect effective config values and sources
/compact                               # Summarize history to reclaim context

Note: codex --verbose is not a valid top-level flag. Use the debug subcommands and TUI diagnostics above.

Clean Reinstall

npm uninstall -g @openai/codex && npm install -g @openai/codex@latest

Debug Mode

codex debug app-server send-message-v2  # Test app-server client

Reporting Issues

/feedback                              # Send logs to Codex maintainers (in TUI)

Or file issues at github.com/openai/codex/issues.¹

Enterprise Deployment

Admin Controls (requirements.toml)

Enterprise policy is enforced via requirements.toml, an admin-enforced configuration file that constrains security-sensitive settings users cannot override:²²

# /etc/codex/requirements.toml

# Restrict which approval policies users can select
allowed_approval_policies = ["untrusted", "on-request", "on-failure"]

# Limit available sandbox modes
allowed_sandbox_modes = ["read-only", "workspace-write"]

# Control web search capabilities
allowed_web_search_modes = ["cached"]

# Allowlist MCP servers by identity (both name and identity must match)
[mcp_servers.approved-server]
identity = { command = "npx approved-mcp-server" }

# Admin-enforced command restrictions
[[rules.prefix_rules]]
pattern = [{ token = "rm" }, { any_of = ["-rf", "-fr"] }]
decision = "forbidden"
justification = "Recursive force-delete is prohibited by IT policy"

[[rules.prefix_rules]]
pattern = [{ token = "sudo" }]
decision = "prompt"
justification = "Elevated commands require explicit approval"

Unlike user-level config.toml which sets preferences, requirements.toml is a hard constraint layer — it restricts what values users can select, and users cannot override it. Admin requirements rules can only prompt or forbid (never silently allow).

macOS MDM Configuration

Distribute via MDM using the com.openai.codex preference domain. Codex honors standard macOS MDM payloads (Jamf Pro, Fleet, Kandji, etc.) — encode TOML as base64 without line wrapping:

Precedence (highest to lowest):

1. macOS managed preferences (MDM)
2. Cloud-fetched requirements (ChatGPT Business / Enterprise)
3. /etc/codex/requirements.toml (local filesystem)

Cloud requirements only fill unset requirement fields, so higher-precedence managed layers always win. Cloud requirements are best-effort — if the fetch fails or times out, Codex continues without the cloud layer.

OpenTelemetry Integration

Codex supports OpenTelemetry trace-context propagation from standard OTel environment variables through to OpenAI API calls. Configure OTel in your runtime/collector stack:

• Standard OTEL_* environment variables are respected
• Trace context propagates through Codex to API calls
• Keep privacy requirements in mind when enabling prompt/tool logging

Enterprise Access

• ChatGPT Business / Enterprise / Edu: Org-admin controlled access, with cloud-fetched requirements applied automatically
• API: Standard API auth, billing, and org/project controls
• Codex SDK: Embed in internal tools and workflows
• Policy enforcement at scale: Use MDM-distributed requirements_toml_base64 or filesystem-level /etc/codex/requirements.toml

Community Tips & Techniques

Prompting Patterns

1. Constraint-driven prompts: Lead with boundaries — “Do NOT change the API contracts. Only refactor internal implementation.”
2. Structured reproduction steps: Numbered steps produce better bug fixes than vague descriptions
3. Verification requests: End with “Run lint + the smallest relevant test suite. Report commands and results.”
4. File references: Use @filename to attach specific files to context
5. Outcome-driven loops: “Implement, run tests, fix failures, stop only when all tests pass” — Codex iterates until done

Testing Philosophy

The community converges on test-driven AI collaboration:²³

• Define tests upfront as completion signals
• Let Codex iterate until tests pass (red → green → refactor)
• Adopt Tiger Style programming patterns
• Provide exact file text when requesting patches — Codex uses strict matching, not fuzzy AST-based patching

Context Management Best Practices

• Provide high-quality local documentation rather than relying on web search
• Maintain structured markdown with tables of contents and progress files (“progressive disclosure”)
• Normalize line endings (LF vs CRLF) across tracked files to prevent patch failures
• Keep AGENTS.md concise — long instructions get pushed out of context

Git Workflow

• Always create a new branch before running Codex on unfamiliar repos
• Use patch-based workflows (git diff / git apply) rather than direct edits
• Review Codex suggestions like code review PRs
• Use /diff to verify changes before committing

Community Skills and Prompts

The feiskyer/codex-settings repository provides battle-tested configurations:²⁴

Reusable prompts (in ~/.codex/prompts/): - deep-reflector: Extract learnings from development sessions - github-issue-fixer [issue-number]: Systematic bug analysis and PR creation - github-pr-reviewer [pr-number]: Code review workflows - ui-engineer [requirements]: Production-grade frontend development

Community skills: - claude-skill: Handoff tasks to Claude Code with permission modes - autonomous-skill: Multi-session task automation with progress tracking - deep-research: Parallel sub-task orchestration - kiro-skill: Requirements → design → tasks → execution pipeline

Migration Guide

From Claude Code

Key differences to understand:

• Sandbox is OS-level: Codex uses Seatbelt/Landlock, not containers. Restrictions are harder to escape.
• No hooks: Codex doesn’t have a direct 1:1 equivalent to Claude Code hooks. Use AGENTS.md instructions or skills instead.
• No subagents: Codex doesn’t have a direct 1:1 local subagent model. Use cloud tasks or SDK orchestration for delegation.
• AGENTS.md is cross-tool: Your AGENTS.md works in Cursor, Amp, and Jules too. CLAUDE.md is Claude-only.
• Profiles replace manual switching: Instead of changing flags per-run, define profiles in config.toml.

From GitHub Copilot

What you gain: - Full agentic capability (file editing, command execution, git operations) - Cloud task delegation - OS-level sandboxing - MCP integrations

From Cursor

Quick Reference Card

╔═══════════════════════════════════════════════════════════════╗
║                    CODEX CLI QUICK REFERENCE                  ║
╠═══════════════════════════════════════════════════════════════╣
║                                                               ║
║  LAUNCH                                                       ║
║  codex                      Interactive TUI                   ║
║  codex "prompt"             TUI with initial prompt           ║
║  codex exec "prompt"        Non-interactive mode              ║
║  codex app                  Desktop app                       ║
║  codex resume               Resume previous session           ║
║  codex fork                 Fork a session                    ║
║                                                               ║
║  FLAGS                                                        ║
║  -m, --model <model>        Select model                      ║
║  -p, --profile <name>       Load config profile               ║
║  -s, --sandbox <mode>       Sandbox mode                      ║
║  -C, --cd <dir>             Working directory                 ║
║  -i, --image <file>         Attach image(s)                   ║
║  -c, --config <key=value>   Override config                   ║
║  --full-auto                workspace-write + on-request      ║
║  --oss                      Use local models (Ollama)         ║
║  --search                   Enable live web search            ║
║                                                               ║
║  SLASH COMMANDS (in TUI)                                      ║
║  /compact      Free tokens   /diff        Git diff            ║
║  /review       Code review   /plan        Plan mode           ║
║  /model        Switch model  /status      Session info        ║
║  /fork         Fork thread   /init        AGENTS.md scaffold  ║
║  /mcp          MCP tools     /skills      Invoke skills       ║
║  /ps           Background    /personality Style               ║
║  /permissions  Approval mode /statusline  Footer config       ║
║                                                               ║
║  TUI SHORTCUTS                                                ║
║  @              Fuzzy file search                             ║
║  !command       Run shell command                             ║
║  Ctrl+G         External editor                               ║
║  Enter          Inject instructions (while running)           ║
║  Esc Esc        Edit previous messages                        ║
║                                                               ║
║  EXEC MODE (CI/CD)                                            ║
║  codex exec --full-auto "task"          Sandboxed auto        ║
║  codex exec --json -o out.txt "task"    JSON + file output    ║
║  codex exec --output-schema s.json      Structured output     ║
║  codex exec resume --last "continue"    Resume session        ║
║                                                               ║
║  MCP MANAGEMENT [experimental]                                ║
║  codex mcp add <name> -- <cmd>    Add STDIO server            ║
║  codex mcp add <name> --url <u>   Add HTTP server             ║
║  codex mcp list                    List servers                ║
║  codex mcp login <name>           OAuth flow                  ║
║  codex mcp remove <name>          Delete server               ║
║                                                               ║
║  CLOUD [EXPERIMENTAL]                                         ║
║  codex cloud exec --env <ID> Start cloud task                 ║
║  codex cloud status <ID>     Check task progress              ║
║  codex cloud diff <ID>       View task diff                   ║
║  codex cloud list            List tasks                       ║
║  codex apply <TASK_ID>       Apply cloud diff locally         ║
║                                                               ║
║  CONFIG FILES                                                 ║
║  ~/.codex/config.toml        User config                      ║
║  .codex/config.toml          Project config                   ║
║  ~/.codex/AGENTS.md          Global instructions              ║
║  AGENTS.md                   Project instructions             ║
║  requirements.toml           Enterprise policy constraints    ║
║                                                               ║
║  SANDBOX MODES                                                ║
║  read-only          Read files only, no mutations             ║
║  workspace-write    Read/write in workspace + /tmp            ║
║  danger-full-access Full machine access                       ║
║                                                               ║
║  APPROVAL POLICIES                                            ║
║  untrusted     Prompt for all mutations                       ║
║  on-failure    Auto-run until failure                         ║
║  on-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (Feb 2026)                                            ║
║  gpt-5.3-codex         Default flagship (272K input)          ║
║  gpt-5.3-codex-spark   Interactive, lower latency (128K)     ║
║  gpt-5.2-codex         Long-horizon refactors (272K input)   ║
║  gpt-5.1-codex-mini    Quick tasks, cost-efficient (272K in) ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Changelog

References