Codex CLI v0.130 Reference: codex remote-control, Multi-Environment view_image, Bedrock AWS-login Auth

TL;DR: Codex is a multi-surface coding agent that reads your codebase, runs commands in an OS-level sandbox, patches files, and delegates tasks to the cloud. Master five core systems (config.toml, sandbox/approval model, AGENTS.md, MCP, and skills) and Codex becomes a force multiplier. Use profiles for context-switching, /compact to manage the context budget, /goal for persisted work goals, and AGENTS.md for cross-tool project instructions that work in Codex, Cursor, Amp, and more. GPT-5.5 (launched April 23, 2026) is the recommended default in Codex — 400K context window in Codex (1M in the API), $5/$30 per MTok, 82.7% Terminal-Bench 2.0 SOTA.⁸³ As of CLI v0.130.0 (May 8, 2026), Codex ships a top-level codex remote-control command for headless app-server control, multi-environment view_image resolution, Bedrock auth via AWS aws login console-login credentials, app-server thread pagination, plugin-detail visibility for bundled hooks with share-link metadata and discoverability controls, live config refresh on running threads, configurable OpenTelemetry trace metadata, and continued sandbox hardening on Linux and Windows. v0.129.0 (May 7, 2026) added modal Vim editing (/vim), a redesigned workflow picker, an in-TUI /hooks browser, a theme-aware status line, plugin workspace sharing with marketplace operations, and a /goal lifecycle change. Continue to prefer explicit sandbox/approval flags or permission profiles over legacy --full-auto; js_repl remains removed.^86878991

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 five distinct surfaces depending on how you work, including the new Chrome extension that runs Codex in your browser without taking it over.⁹⁰

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 complete 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] or under development are subject to change between releases. As of v0.130.0 (May 8, 2026), Codex Cloud and code mode remain experimental or under development, while core CLI, sandboxing, AGENTS.md, config.toml, Skills, hooks, multi-agent tools, and plugins are stable surfaces. v0.130.0 adds the codex remote-control top-level command (simpler entrypoint for a headless, remotely-controllable app-server), multi-environment view_image resolution, Bedrock auth via AWS aws login console-login credentials, app-server thread pagination with unloaded / summary / full turn views, plugin detail visibility for bundled hooks plus share-link metadata and discoverability controls, live app-server config refresh (running threads pick up config changes without restart), removed “research preview” wording from the codex exec startup banner, configurable OpenTelemetry trace metadata, Linux sandbox startup hardening, and Windows sandbox grant for the desktop runtime binary cache.⁹¹ v0.129.0 (May 7, 2026) added modal Vim editing in the composer (/vim + configurable default-mode), a redesigned TUI workflow picker (easier resume/fork, raw scrollback), the /hooks browser, a theme-aware status line with optional PR + branch summaries, plugin workspace sharing + marketplace operations + share access controls + source filtering, a /goal lifecycle change (experimental goals stay paused across resume unless opted back in), Linux sandbox startup hardening, Windows sandbox reliability improvements, and a Bubblewrap bump to 0.11.2 with upstream security patches.⁸⁹ v0.128.0 (April 30, 2026) introduced persisted /goal workflows, codex update, configurable TUI keymaps, and expanded permission profiles; legacy --full-auto remains deprecated and js_repl remains removed.⁸⁶⁸⁷

Key Takeaways

• Five surfaces, one brain: CLI, desktop app, IDE extension, cloud tasks, and the new Chrome extension all share the same GPT-5.x-Codex intelligence, so 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, Copilot, Amp, Jules, Gemini CLI, Windsurf, Cline, Aider, Zed, and 60,000+ open source projects. Write once, use everywhere.
• Profiles save context-switching overhead: Define named config presets (fast, careful, auto) and switch between them with --profile.
• Context management matters: GPT-5.4 offers 1M context; GPT-5.4 mini provides 400K for subagent work; GPT-5.3-Codex provides 272K input. Use /compact, focused prompts, and @file references to manage token budgets proactively.

How to Use This Guide

This is a 2,500+ line reference — start where your experience level fits:

The Quick Reference Card at the end provides a scannable summary of all major commands.

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         │    │
│  │   (legacy artifact, read_file, grep_files       │    │
│  │    removed in v0.117.0)                          │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens          │
└─────────────────────────────────────────────────────────┘

Core Layer: The GPT-5.x model family powers everything. As of April 23, 2026, gpt-5.5 is the recommended model when available — 400K context in Codex (1M in the API), 82.7% Terminal-Bench 2.0 SOTA. gpt-5.4 remains the fallback default during rollout (1M context, native computer use).⁸³⁶⁴ 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. Quick Start: Your First Session
3. Core Interaction Surfaces
4. Configuration System Deep Dive
5. Which Model Should I Choose?
6. What Does Codex Cost?
7. Decision Frameworks
8. How Does the Sandbox & Approval System Work?
9. How Does AGENTS.md Work?
10. Hooks
11. What Is MCP (Model Context Protocol)?
12. Code Mode
13. JavaScript REPL Runtime
14. What Are Skills?
15. Plugins
16. Plan Mode & Collaboration
17. Memory System
18. Session Management
19. Non-Interactive Mode (codex exec)
20. Codex Cloud & Background Tasks
21. The Codex Desktop App
22. GitHub Action & CI/CD
23. Codex SDK
24. Performance Optimization
25. How Do I Debug Issues?
26. Enterprise Deployment
27. Best Practices & Anti-Patterns
28. Workflow Recipes
29. Migration Guide
30. Quick Reference Card
31. Changelog
32. References

How Do I Install Codex?

Package Managers

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

# Homebrew (macOS)
brew install --cask codex

# winget (Windows)
winget install OpenAI.Codex

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

Direct Install Script (v0.106.0+)

For macOS and Linux, a one-line install script is available as a GitHub release asset:⁶⁰

curl -fsSL https://github.com/openai/codex/releases/latest/download/install.sh | sh

The script auto-detects your platform and architecture, downloads the correct binary, and places it on your PATH.

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: Native sandbox with restricted tokens (promoted from experimental in v0.100.0). WSL also supported²

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

Quick Start: Your First Session

Get from zero to productive in 5 minutes.

1. Install and authenticate:

npm i -g @openai/codex          # Install
codex login                      # Log in with your OpenAI account

2. Navigate to a project:

cd ~/my-project                  # Any git repo works

3. Start Codex:

codex

You’ll see the interactive TUI. Codex reads your project structure automatically.

4. Ask a question:

> What does this project do? Summarize the architecture.

Codex reads key files and explains the codebase. No changes are made in the default suggest mode.

5. Make a change:

> Add input validation to the login endpoint

Codex proposes edits as a diff. Review and approve with y, or reject with n.

6. Use a slash command:

> /plan Refactor the database layer to use connection pooling

Codex creates a plan without executing. Review the plan, then approve to begin execution.

7. Check your work:

> /diff

See all changes Codex has made in the current session.

What’s next: - Set up AGENTS.md with project instructions (see How Does AGENTS.md Work?) - Configure a profile for your workflow (see Profiles) - Try codex exec for non-interactive automation (see Non-Interactive Mode)

Core Interaction Surfaces

Codex provides four distinct interfaces backed by the same intelligence. Each surface optimizes 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.5            # Specify model
codex --sandbox workspace-write --ask-for-approval on-request

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:

Status line change (v0.121.0): The old context-window meter in the status line has been replaced by a context-percent indicator showing how full your context window is. If you have scripts or hooks parsing the status line, check for this format change.⁸² Codex will also surface a CLI update announcement when a new version is available.

Slash commands available in the TUI:

Workflow picker redesign (v0.129.0): Resume and fork are now easier to reach from a redesigned picker, and a new raw scrollback mode lets you scroll through the unrendered transcript when you need to copy commands or model output verbatim. Useful when triaging a long debugging session or piping output to another tool.⁸⁹

2. Codex Desktop App (macOS + Windows)

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

5. Codex for Chrome [NEW]

Codex ships as a browser extension for Chrome, adding a fifth surface alongside the CLI, desktop app, IDE extension, and cloud. The extension is designed to ride alongside your normal browsing rather than take it over: Codex works in parallel across tabs in the background, and you stay in control of which sites it touches.⁹⁰

• Parallel tab execution: Codex operates across multiple tabs at once without locking the foreground tab.
• Per-site control: You allow-list which websites Codex can interact with; default is no access.
• Browser as the workbench: The extension is best for app-and-website work where the page is the source of truth — admin consoles, internal dashboards, content-management UIs, ticket systems — not a replacement for the CLI on local repos.
• Same brain: Codex for Chrome runs the same GPT-5.x-Codex intelligence the other surfaces use, so an AGENTS.md or skills configuration that works in the CLI carries the same conventions into browser-driven work.

Install from the Codex Chrome extension docs.⁹⁰

Configuration System Deep Dive

Codex uses TOML for configuration. Understanding the precedence hierarchy is critical because 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 that 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.5"                      # Recommended model when available
model_provider = "openai"               # Provider (openai, oss, or custom provider id)
model_context_window = 272000           # Token count available to active model (override)
model_auto_compact_token_limit = 200000 # Threshold triggering automatic history compaction
model_reasoning_effort = "medium"       # minimal|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.5"               # Optional 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-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 ─────────────────────────────────
allow_login_shell = false               # Allow login shell semantics (loads .profile/.zprofile)

[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
mcp_oauth_callback_port = 0            # Fixed port for MCP OAuth callback (0 = random)
mcp_oauth_credentials_store = "auto"   # auto|file|keyring

# ─── 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)
command_attribution = true              # Codex co-author in commits (v0.103.0+)
request_user_input = true               # Allow agent to ask clarifying questions in Default mode (v0.106.0+)
multi_agent = false                     # Enable multi-agent collaboration tools (v0.102.0+)
apply_patch_freeform = false            # Expose freeform apply_patch tool
apps = false                            # ChatGPT Apps/connectors (experimental)
child_agents_md = false                 # AGENTS.md guidance (experimental)
runtime_metrics = false                 # Runtime summary in turns
search_tool = false                     # Enable search_tool_bm25 for Apps discovery

# ─── Multi-Agent Roles (v0.102.0+) ───────────────────
[agents]
max_threads = 4                         # Maximum concurrent agent threads

[agents.explorer]
description = "Read-only codebase navigator"
config_file = "~/.codex/profiles/explorer.toml"

# ─── Notifications ────────────────────────────────────
notify = ["terminal-notifier", "-title", "Codex"]  # Command for notifications

# ─── Per-Project Overrides ────────────────────────────
[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.4"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

[profiles.auto]
model = "gpt-5.4"
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, AWS Bedrock, 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"

# Built-in amazon-bedrock provider (v0.123.0+, first-class in v0.124.0+)
# AWS SigV4 signing + credential-based auth; AWS profile selectable via the
# nested `aws.profile` field (NOT a top-level `aws_profile` key).
# v0.130.0+ also accepts credentials from `aws login` (the AWS console-login
# flow) — Codex resolves the cached console-login session for the chosen
# profile if static keys are absent.
[model_providers.amazon-bedrock]
name = "Amazon Bedrock"

[model_providers.amazon-bedrock.aws]
profile = "default"                   # any profile from ~/.aws/credentials
# Region/credential resolution otherwise follows the standard AWS chain;
# v0.130.0 added support for `aws login` console-login profiles in addition
# to static access keys and IAM role assumption.[^168]

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

Warning: The chat/completions wire API (wire_api = "chat") was deprecated for OpenAI-hosted models, with OpenAI announcing removal in February 2026.³⁴ Local providers (Ollama, LM Studio) may still accept this format. For OpenAI endpoints, use wire_api = "responses" instead.

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.5" "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 (April 2026)

GPT-5.5 (April 23, 2026) is OpenAI’s recommended choice for most Codex tasks: complex coding, computer use, knowledge work, and research workflows. Available in Codex CLI / web / desktop on April 23 for ChatGPT Plus / Pro / Business / Enterprise / Edu / Go; in the OpenAI API on April 24. Context window: 400K in Codex, 1M in the API — Codex caps the window at 400K to balance throughput and cost across subscriber tiers; the API exposes the full 1M. Pricing (API): $5 input / $30 output per MTok (2× the GPT-5.4 rate; OpenAI states ~20% effective increase after token-efficiency improvements). Benchmarks: 82.7% Terminal-Bench 2.0 (current SOTA across publicly available models), 84.9% GDPval (44 occupations), 78.7% OSWorld-Verified, 98.0% Tau2-bench Telecom (no prompt tuning). OpenAI used GPT-5.5 + Codex internally to rewrite serving infrastructure pre-launch — yielded a 20% boost in token generation speed.⁸³

GPT-5.4 stays available across all Codex surfaces (CLI, app, IDE extension, cloud).⁶⁴ The exact model list varies by account and rollout. Check your local cache: ~/.codex/models_cache.json.

Deprecation note (March 11, 2026): GPT-5.1 models are no longer available in ChatGPT. Existing conversations automatically continue on GPT-5.3 Instant, GPT-5.4 Thinking, or GPT-5.4 Pro. GPT-5.1-Codex-Mini remains available via API and CLI for cost-sensitive workloads.⁷¹

Free-tier note (May 5, 2026): GPT-5.5 Instant rolled out to the ChatGPT free tier on May 5, 2026. This widens the audience for the GPT-5.5 family beyond paid plans, though Codex CLI access continues to require an eligible Plus / Pro / Business / Enterprise / Edu / Go subscription or API key.⁹²

GPT-5.4 mini (March 17, 2026): A smaller, faster variant of GPT-5.4 with 400K context at $0.75/$4.50 per MTok — uses only 30% of GPT-5.4 quota. Ideal for subagent delegation: let GPT-5.4 handle planning and coordination while GPT-5.4 mini subagents handle narrower subtasks (codebase search, file review, document processing) in parallel.⁷⁶

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 (near-instant, Pro only)
   │  └─ No
   │     ├─ Subagent or parallel subtask (search, review, processing)?
   │     │  ├─ Yes → gpt-5.4-mini (30% of GPT-5.4 quota, 2x faster)
   │     │  └─ No
   │     │     ├─ Pure coding task (refactor, migration, feature build)?
   │     │     │  ├─ Yes → gpt-5.3-codex (coding specialist, 272K context)
   │     │     │  └─ No → gpt-5.5 (new flagship: 400K context in Codex / 1M in API, 82.7% Terminal-Bench 2.0 SOTA)
   └─ Still unsure? → gpt-5.5

Reasoning Effort

Control how much the model “thinks” before responding:

Supported levels are model-dependent. minimal is only available for GPT-5 models. 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.

TUI quick reasoning controls (v0.124.0+).⁸⁵ In an interactive TUI session, Alt+, lowers reasoning one step and Alt+. raises it one step — useful when a hard problem mid-session warrants a temporary medium → high → xhigh ramp without /effort or -c. When you accept a model upgrade mid-session, reasoning resets to the new model’s default rather than carrying the prior level over.

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"

What Does Codex Cost?

See also Model Selection for capabilities and Decision Frameworks for choosing the right model per task.

Access via ChatGPT Plans

Codex availability depends on your ChatGPT plan and organization settings:⁵¹

April 2026 pricing update: Business annual pricing dropped from $25 to $20/seat/mo. Codex-only seats with pay-as-you-go pricing are now available for Business and Enterprise workspaces — no fixed seat fee, billed on token consumption.⁷⁹ Promotional 2x rate limits for paid plans (from the February 2026 Desktop App launch) remain active.¹⁶

May 2026 usage limit boost (through May 31, 2026): Codex on the Plus plan runs at a 25× 5-hour limit (vs the standard 20× boost), and the $100/month tier is doubled for the same window. Use this period to push longer cloud-task batches or higher-throughput agent runs without hitting your normal 5-hour wall.⁸⁹

Credit Costs

Codex operations consume credits from your plan allocation:

Enterprise and Edu plans scale credits with contract allocation. Check /status in the TUI for current usage.

API Billing

When using Codex through the API, OpenAI bills usage 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, as 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

Real-World Cost Examples

Representative API costs for common tasks (gpt-5.3-codex at standard pricing, medium reasoning):

Costs vary by reasoning effort, caching, and conversation length. Use gpt-5.1-codex-mini for routine tasks to reduce costs by ~40-60%. Cached input tokens are billed at a discount.

Hidden Token Overhead

Every tool call adds tokens beyond your visible prompt:

Expert tip: Monitor your actual usage via /status in the TUI. The token count includes all overhead, not just your visible messages. If costs surprise you, check how many MCP servers are connected — each adds tool definitions to every API call.

Team Cost Management

Strategies for team cost control: - Set requirements.toml to enforce model and reasoning effort limits organization-wide - Use gpt-5.1-codex-mini for CI/CD — automated pipelines rarely need maximum reasoning - Profile-based budgeting — define ci, review, and dev profiles with appropriate cost ceilings - Monitor via OpenTelemetry — enterprise deployments can export usage telemetry to existing observability stacks

Decision Frameworks

When to Use Each Surface

When to Use Each Sandbox Mode

When to Use Each Reasoning Level

Plan Mode vs Direct Execution

Will Codex need to change more than 3 files?
│
├── YES → Use Plan Mode (/plan)
│         Codex designs the approach BEFORE making changes.
│         You review and approve the plan.
│         Best for: refactors, new features, migrations
│
└── NO → Is the change well-defined?
         │
         ├── YES → Direct execution
         │         Just describe the task. Codex executes immediately.
         │         Best for: bug fixes, small features, test additions
         │
         └── NO → Use Plan Mode (/plan)
                  Let Codex explore and propose an approach first.
                  Best for: unfamiliar codebases, ambiguous requirements

Steer Mode: Enter vs Tab

Rule of thumb: Enter = “stop, listen to this now.” Tab = “when you’re done, also do this.”

Desktop App vs CLI

How do you prefer to work?
│
├── Terminal-first → Use CLI
│   │
│   ├── Single focused task → codex (interactive TUI)
│   ├── Scripted automation → codex exec (non-interactive)
│   └── Quick one-shot → codex exec "prompt" -o result.txt
│
└── Visual/multi-project → Use Desktop App
    │
    ├── Multiple parallel tasks → Multi-thread with worktree isolation
    ├── Visual diff review → Built-in Git diff viewer
    ├── Scheduled automation → Automations tab
    └── Voice-driven → Ctrl+M for voice dictation

Which Profile?

Match your task to a pre-configured profile:

config.toml setup:

# Default profile
profile = "default"

[profiles.fast]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"

[profiles.careful]
model = "gpt-5.3-codex"
model_reasoning_effort = "xhigh"

[profiles.pair]
model = "gpt-5.3-codex-spark"
model_reasoning_effort = "high"

[profiles.ci]
model = "gpt-5.1-codex-mini"
model_reasoning_effort = "low"
sandbox_mode = "workspace-write"

Switch profiles per-session: codex --profile careful

How Does the Sandbox & Approval System Work?

Codex uses a two-layer security model that separates what is technically possible from when Codex asks for human approval. The approach differs fundamentally from Claude Code’s permission system — Codex enforces restrictions at the OS kernel level.⁵ See also Enterprise Deployment for requirements.toml constraints that administrators enforce organization-wide.

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⁶. As of v0.121.0, macOS sandbox profiles can allowlist specific Unix sockets (e.g., docker.sock, editor IPC sockets) and private DNS resolution is no longer blocked by default.⁸²
• Linux: Landlock for filesystem restrictions + seccomp for syscall filtering. A standalone helper process (codex-linux-sandbox) provides defense-in-depth isolation.⁵ Bubblewrap (bwrap) is vendored and compiled as part of the Linux build (promoted from optional in v0.100.0)⁷. v0.117.0 improved sandbox reliability on older distros with legacy kernel configurations.⁷⁵ v0.129.0 hardened sandbox startup on Linux and bumped vendored Bubblewrap to 0.11.2 with upstream security patches; v0.130.0 added further startup hardening.⁸⁹⁹¹
• Windows: Native sandbox with restricted tokens (promoted from experimental in v0.100.0). WSL also supported (inherits Linux Landlock + seccomp). v0.117.0 includes restricted-token sandbox improvements for better process isolation.⁷⁵ v0.130.0 grants sandbox users access to the desktop runtime binary cache so that the Windows sandbox can resolve runtime binaries reliably for workspace-sandbox users.⁹¹

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.

Security fixes: - zsh-fork sandbox bypass (v0.106.0): Fixed a vulnerability where shell execution via zsh forking could bypass sandbox restrictions.⁶⁰ If you are on an earlier version, upgrade immediately. - Input size cap (v0.106.0): Codex now enforces an approximately 1-million-character input cap to prevent hangs from excessively large payloads.⁶⁰ - Secure devcontainer profile (v0.121.0): A new hardened customer profile for Docker devcontainers uses Bubblewrap for sandboxing inside the container. WSL2 is supported; WSL1 is explicitly rejected (Bubblewrap is incompatible with WSL1’s kernel shim).⁸² - Guardian review + hooks (v0.121.0): Hooks are disabled during Guardian review sessions so pre/post-tool hooks cannot interfere with the Guardian subagent’s decisions.⁸² If you rely on hooks for logging or validation, be aware that a Guardian review skips them — fall back on app-server observability if you need a full audit trail. - Linux /dev filesystem (v0.105.0): Sandboxed commands on Linux now receive a minimal /dev filesystem, improving compatibility with tools that expect device nodes.⁶¹

ReadOnlyAccess policy (v0.100.0+): A configurable policy shape for granular read access control. Use it to restrict which directories Codex can read from, even in workspace-write mode:

[sandbox_workspace_write]
read_only_access = ["/etc", "/usr/local/share"]  # Only these paths readable outside workspace

Layer 2: Approval Policy (When To Ask)

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

on-failure still appears in some older examples and compatibility paths, but current OpenAI configuration docs mark it deprecated. Prefer on-request for interactive runs and never for non-interactive runs that already have an external safety boundary.⁸⁷

Distinct Approval IDs (v0.104.0+)

Codex now assigns distinct approval IDs to each command within a multi-step shell execution. This means approvals are granular — approving one command in a sequence doesn’t automatically approve subsequent ones in the same shell invocation.⁴⁹

Flexible Approval Controls (v0.105.0+)

The approval flow now supports extra sandbox permissions and granular rejection:⁶¹

• Extra sandbox permissions: When a command needs access beyond the current sandbox mode, Codex can request specific additional permissions rather than requiring a full mode change
• Granular rejection: Reject individual tool calls with feedback so Codex can adjust its approach rather than simply re-attempting the same command

Runtime Permission Requests (v0.113.0+)

Codex now includes a built-in request_permissions tool that allows the model to request additional permissions at runtime.⁶⁹ When the model encounters a task requiring elevated access, it can formally request specific permissions (filesystem paths, network access, etc.) through the TUI approval flow rather than failing silently or requiring the user to restart with different flags.

Permission Profiles (v0.113.0+, expanded in v0.128.0)

Permission profiles split filesystem and network sandbox policies into named, reusable sections. Set default_permissions to a built-in profile such as :read-only, :workspace, or :danger-no-sandbox, or point it at a custom [permissions.<name>] table.⁸⁷

default_permissions = "project-safe"

[permissions.project-safe.filesystem]
"/usr/local" = "read"
glob_scan_max_depth = 3

[permissions.project-safe.filesystem.":project_roots"]
"." = "write"
"**/*.env" = "none"

[permissions.project-safe.network]
enabled = true
mode = "limited"

[permissions.project-safe.network.domains]
"api.github.com" = "allow"
"registry.npmjs.org" = "allow"

Use none for sensitive files and globs that should be unreadable even when the project root is writable. For one-off command exceptions, prefer rules over broadly expanding a profile.⁸⁷

Legacy --full-auto Guidance

Older guides described --full-auto as a convenience alias for:

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

In v0.128.0, release notes mark --full-auto deprecated, and current CLI help no longer lists it for interactive runs. Use the explicit flags above or a named permissions profile instead.⁸⁶

Sandbox reliability (v0.129.0): Linux sandbox startup hardening reduces races on slow filesystems or symlinked checkouts; Windows sandbox reliability improvements address several edge-case crashes during long-running runs; and the vendored Bubblewrap is bumped to 0.11.2 with upstream security patches. No config changes required. Run codex update to pick these up.⁸⁹

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"

The combination is the community-recommended “sweet spot”: maximum capability but approval required for every command.⁸

CI/CD automation:

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

Smart Approvals with Guardian Subagent (v0.115.0+)

Smart Approvals can route review requests through a guardian subagent instead of requiring human approval for every action. The guardian session persists across approvals to reuse prompt cache and avoid startup overhead. Each review gets a clean history (prior decisions don’t leak into later reviews).⁷³

Configure the reviewer in config.toml:

approvals_reviewer = "guardian_subagent"   # "user" (default) or "guardian_subagent"

This is particularly useful for CI/CD workflows where you want automated review with reasoning rather than blanket approval_policy = "never".

Enabling Network Access

Codex blocks network access 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

WebSocket Proxy Support (v0.104.0+)

For corporate environments that route WebSocket traffic through a proxy, Codex now supports WS_PROXY and WSS_PROXY environment variables:⁴⁹

export WSS_PROXY="https://proxy.corp.example.com:8443"
codex "update the README"

These complement the existing HTTPS_PROXY and SOCKS5 proxy support (v0.93.0+), covering all transport layers.

Testing the Sandbox

Verify sandbox behavior before trusting it:

codex sandbox macos --permissions-profile :workspace -- ls /etc/passwd   # macOS test
codex sandbox linux --permissions-profile :workspace -- cat /etc/shadow  # Linux test

If the sandbox is working correctly, both commands should fail with a permission denied error under a workspace-scoped profile. If either command succeeds, your sandbox configuration needs investigation.

How Does AGENTS.md Work?

AGENTS.md is Codex’s project instruction system — an open standard⁹ now governed by the Linux Foundation’s Agentic AI Foundation. Supported by Codex, Cursor, Copilot, Amp, Jules (Google), Gemini CLI, Windsurf, Cline, Aider, Zed, Factory, RooCode, and 60,000+ open source projects. It defines how Codex behaves within a specific repository or directory. See Skills for reusable expertise packages that complement AGENTS.md.

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"

Hooks

Codex introduced hooks in v0.99.0 (AfterAgent) and v0.100.0 (AfterToolUse), then added an experimental hooks engine in v0.114.0 with SessionStart and Stop events.⁷⁰ As of v0.124.0 (April 23, 2026), hooks are stable.⁸⁵ They are now configurable inline in config.toml and requirements.toml — no more separate hook scripts file required — and they observe MCP tools alongside apply_patch and long-running Bash sessions. The system now covers session lifecycle and tool-level automation, closing the gap with Claude Code’s hook model.

Available Hook Events

Hook Configuration

Hooks are configured in .codex/config.toml:

[[hooks]]
event = "AfterToolUse"
command = "echo 'Tool completed' >> /tmp/codex-log.txt"

[[hooks]]
event = "SessionStart"
command = "echo 'Current date: $(date +%Y-%m-%d)'"

The SessionStart hook’s stdout feeds into the model’s context, making it ideal for injecting dynamic information (dates, branch names, environment variables) at session start.

Replicating Claude Code Hook Patterns

If migrating from Claude Code, here’s how to achieve similar automation:

Expert tip: As of v0.124.0 (April 23, 2026) the hooks engine is stable. New hook events still ship in releases — check the Codex changelog.

In-TUI hook browser (v0.129.0): Run /hooks in the TUI to discover available hooks, see which are currently active, and toggle individual hooks without editing config.toml. Useful when troubleshooting a misbehaving plugin-bundled hook or temporarily disabling an AfterToolUse linter for a heads-down editing session.⁸⁹

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, and commands and config format may change between releases. Codex supports two transport types: STDIO (local processes) and Streamable HTTP (remote servers).¹¹

v0.121.0 MCP changes: Tools are now registered with a namespace, so tool names in listings appear as <server>:<tool> rather than bare names — update any scripts or prompts that grep against unqualified tool names. A new supports_parallel_tool_calls flag is plumbed through to included MCPs, enabling parallel execution for servers that declare support. Sandbox-state metadata now flows through MCP tool metadata so servers can adapt behavior (e.g., warn if running under a read-only sandbox). The custom codex/sandbox-state request has been removed — use the metadata path instead. Phase 3 of the MCP Apps rollout lands here with tool-call support; flattened deferred tool calls are now supported for servers using the deferred-call pattern.⁸²

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. /mcp verbose (v0.123.0+)⁸⁴ returns full server diagnostics, resources, and resource templates — useful when a server is failing to load or tools aren’t appearing where expected. Plain /mcp stays fast.

Plugin MCP loading (v0.123.0+) accepts both the standard mcpServers schema and top-level server maps in .mcp.json, so plugins authored against either convention load cleanly.⁸⁴

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)

The server 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

Practical Patterns

Pattern 1: Context-aware development — Pair Context7 with your framework docs so Codex always has current API references:

[mcp_servers.context7]
enabled = true
required = true
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

Pattern 2: Output limits — MCP tool responses are truncated at ~25K characters by default. For tools that return large payloads (database queries, log captures), use enabled_tools to restrict to specific tools and keep responses focused.

Pattern 2a: Multimodal tool output (v0.107.0) — Custom tools can now return multimodal output (images, rich content) alongside text. This enables tools that produce visual artifacts — screenshots, diagrams, chart renders — to pass them directly to the model for analysis.⁶²

Pattern 3: Enterprise MCP governance — Lock down which MCP servers developers can use via requirements.toml:

# In /etc/codex/requirements.toml — only approved servers allowed
[mcp_servers.approved-internal]
identity = { command = "npx @company/internal-mcp" }

Any server not matching an identity in requirements.toml will be blocked at startup. See Enterprise Deployment for full policy configuration.

Code Mode [EXPERIMENTAL]

Code mode (v0.114.0) provides more isolated coding workflows by restricting the agent’s scope to code-focused operations.⁷⁰ When enabled, the agent focuses on reading, writing, and testing code without broader system interactions.

This feature is experimental. Check release notes for updates.

JavaScript REPL Runtime [REMOVED]

Codex v0.100.0 added an experimental JavaScript REPL runtime (js_repl) and v0.106.0 promoted it through the /experimental surface.⁶⁰ That guidance is now historical. In v0.128.0, the release changelog includes “Remove js_repl feature,” and the current feature list marks both js_repl and js_repl_tools_only as removed.⁸⁶

Do not add features.js_repl = true to new configs. Use shell commands, checked-in scripts, MCP tools, or a Codex skill with a scripts/ directory when you need repeatable executable logic.

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

Codex stores user-installed skills 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 thorough 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: "Full 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

Skills vs Slash Commands

Debugging Skills

If a skill isn’t activating:

1. Check discovery: /skills should list it in the TUI
2. Verify path: Ensure the skill folder is in a recognized location (~/.codex/skills/, project root, or /etc/codex/skills/)
3. Check enabled: Skills with enabled = false in config.toml won’t load
4. Check implicit activation: If relying on auto-detection, ensure allow_implicit_invocation: true in agents/openai.yaml
5. Use keywords: Include the skill’s description terms in your prompt to improve implicit matching

Production Example: Deploy Skill

A complete multi-file skill showing references and scripts working together:

deploy-skill/
  SKILL.md
  references/
    runbook.md
    rollback-checklist.md
  scripts/
    pre-deploy-check.sh
    smoke-test.sh
  agents/openai.yaml

SKILL.md:

---
name: deploy
description: Deploy the application to staging or production. Runs pre-flight checks, executes deployment, and verifies with smoke tests.
---

## Deployment Procedure

### Pre-flight
1. Run `scripts/pre-deploy-check.sh` to verify:
   - All tests pass
   - No uncommitted changes
   - Branch is up to date with remote
2. Review the runbook at `references/runbook.md` for environment-specific steps.

### Deploy
3. Execute the deployment command for the target environment.
4. Monitor logs for errors during rollout.

### Verify
5. Run `scripts/smoke-test.sh <environment-url>` to confirm critical paths.
6. If smoke tests fail, follow `references/rollback-checklist.md`.

Invoke with: $deploy to staging or $deploy production with canary rollout

Plugins

Plugins unify skills, MCP entries, hooks, and app connectors into a single installable package (v0.110.0+).⁶⁵ As of v0.117.0, plugins are first-class citizens: product-scoped plugins sync automatically at startup and /plugins provides an in-TUI browser for discovery and management.⁷⁵ v0.128.0 expanded plugin workflows with marketplace installation, remote bundle caching, remote uninstall APIs, plugin-bundled hooks, hook enablement state, and external-agent config import.⁸⁶ v0.129.0 (May 7, 2026) adds plugin workspace sharing (push a plugin set to teammates without re-publishing), share access controls (per-recipient enable/disable, revoke), source filtering (limit which marketplaces a workspace pulls from), and marketplace operations that can be invoked directly from the /plugins browser instead of the CLI.⁸⁹ v0.130.0 (May 8, 2026) makes plugin packaging more transparent and the share workflow more controllable:⁹¹

• Bundled hooks visible in plugin details. The /plugins detail view now lists every lifecycle hook a plugin bundles (SessionStart, UserPromptSubmit, Stop, etc.). Before installing a plugin, you can see exactly which hooks it will register against your session — no more surprise hook side effects from a plugin you trust on its tools alone.
• Plugin share metadata in shareContext. When a plugin is shared from a workspace, the share-link payload now exposes link metadata (creator, scope, freshness) so receiving sessions can show provenance and decide whether to accept.
• Discoverability controls on share settings. Share settings expose a discoverability toggle so teams can publish plugins to specific workspaces or recipient lists without making them generally listable across an organization.

Plugin Sources

Plugin Discovery

Codex tells the model which plugins are enabled at session start (v0.111.0), improving discovery of installed MCPs, apps, and skills.⁶⁵ The model can suggest relevant plugins during a session based on the task context. In v0.117.0, product-scoped plugins are synced at startup, ensuring the latest plugin catalog is available without manual intervention.⁷⁵

@plugin Mentions (v0.112.0+)

Reference any installed plugin directly in chat with @plugin-name.⁶⁸ When you mention a plugin, its context (capabilities, tools, configuration) is automatically included in the model’s context window — no need to describe what the plugin does.

@deploy push this branch to staging with canary rollout
@linter check for unused imports in src/

This works with any installed plugin, including custom skills, MCP servers, and app connectors.

Plugin Marketplace (v0.113.0+)

The plugin marketplace now includes richer discovery with metadata, categories, and ratings.⁶⁹ Install-time auth checks verify that plugins requiring API keys or OAuth have valid credentials before installation. An uninstall endpoint cleanly removes plugins and their associated configuration.

Adding Third-Party Marketplaces (v0.121.0+)

As of current CLI v0.128.0, marketplace source management lives under codex plugin marketplace. This formalizes third-party plugin distribution beyond OpenAI’s first-party marketplace and supports GitHub repo shorthand, HTTP(S) Git URLs, SSH URLs, and local marketplace root directories.⁸⁶

# GitHub repository (shorthand)
codex plugin marketplace add owner/repo

# Arbitrary git URL
codex plugin marketplace add https://git.example.com/team/plugins.git

# SSH Git URL
codex plugin marketplace add [email protected]:team/plugins.git

# Local directory
codex plugin marketplace add /path/to/local/marketplace

# Upgrade or remove a configured marketplace
codex plugin marketplace upgrade <marketplace-name>
codex plugin marketplace remove <marketplace-name>

Once added, a marketplace’s plugins appear in the /plugins browser alongside the default ones. App-server callers (IDE/desktop integrations) have a parallel endpoint to register marketplaces programmatically.⁸²

Security consideration: Third-party marketplaces run arbitrary plugin code with your Codex permissions. Vet sources before adding them, and prefer sandboxed execution during first runs.

Managing Plugins

codex plugin marketplace add <src>       # Add a marketplace source
codex plugin marketplace upgrade [name]  # Upgrade one marketplace or all
codex plugin marketplace remove <name>   # Remove a configured marketplace

In the TUI, use /plugins (v0.117.0+) to browse, install, and remove individual plugins interactively without leaving your session.⁷⁵

Expert tip: Plugins consolidate what used to require separate MCP config, skill installation, and app connector setup. A single plugin can bundle all three — making team onboarding faster and configuration more portable.

Plan Mode & Collaboration

Plan mode lets Codex design an approach before executing changes. It’s enabled by default (since v0.94.0).¹⁴ See Decision Frameworks for the “Plan Mode vs Direct Execution” decision tree.

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 actively working, without interrupting its current task.¹⁴

There are two injection methods:

Practical examples:

# Codex is refactoring the auth module...

[Enter] "Use bcrypt instead of argon2 — we already have it as a dependency"
→ Codex adjusts immediately, mid-turn

[Tab] "Once auth is done, update the migration script too"
→ Codex finishes auth refactor, then starts the migration

Steer mode is always active in the TUI. If you prefer to wait until Codex finishes before giving instructions, just type normally after the turn completes — no special mode needed.

TUI Enhancements (v0.105.0–v0.106.0)

Syntax highlighting (v0.105.0): The TUI now syntax-highlights fenced code blocks and diffs inline. Use /theme to choose a color scheme.⁶¹

New TUI commands (v0.105.0+):⁶¹

Voice transcription (v0.105.0, experimental): Press spacebar to dictate prompts via voice transcription. This feature is experimental and may require microphone permissions.⁶¹ As of v0.107.0, realtime voice sessions support microphone and speaker device selection, allowing you to choose specific audio input/output hardware.⁶²

Other improvements: - Long links now remain clickable even when wrapped across TUI lines (v0.105.0)⁶¹ - Local file links render with improved formatting (v0.106.0)⁶⁰ - Ctrl+C handling for sub-agents fixed to properly terminate child processes (v0.106.0)⁶⁰

Memory System

Codex has a persistent memory system (v0.100.0+) that stores facts, preferences, and project context across sessions.²⁴

Memory Commands

Memories are stored in markdown files under ~/.codex/memory/. Codex loads them at session start and uses them to inform behavior across all future sessions.

What to Store

Memories work best for persistent preferences and project facts:

• Project conventions: “This project uses tabs, not spaces” or “API responses always include a meta field”
• Tool preferences: “Use pnpm instead of npm” or “Run tests with pytest -x --tb=short“
• Architecture decisions: “The auth module is in src/core/auth/, not src/middleware/“
• Workflow preferences: “Always run the linter before showing me a diff”

Memory in Pipelines

When running codex exec, memories are loaded automatically. This means CI/CD pipelines and scripts benefit from the same context as interactive sessions — no need to repeat instructions in every invocation.

Memory Refinements (v0.101.0–v0.107.0)

• Secret sanitization: Memories are automatically scanned for secrets before being written to disk
• CWD awareness: Memory files now include the working directory context for project-specific recall
• Developer message exclusion: Developer/system messages are excluded from phase-1 memory input, improving memory quality by focusing on user interactions
• Diff-based forgetting (v0.106.0): Memory now uses diff-based forgetting to remove stale facts, keeping the memory store lean and relevant over time⁶⁰
• Usage-aware selection (v0.106.0): Memory retrieval is now usage-aware, prioritizing frequently accessed and recently relevant memories⁶⁰
• Configurable memories (v0.107.0): Memories are now fully configurable. Use codex debug clear-memories to reset all stored memories for a clean slate — useful when switching contexts between unrelated projects or when memory state has drifted⁶²
• Phase-2 model upgrade (v0.121.0): The phase-2 memory consolidation model is now gpt-5.4 (up from the prior default). The phase-2 pipeline runs between sessions to distill phase-1 transcripts into durable facts; the model change improves recall quality at the same token cost.⁸²
• TUI memories menu (v0.121.0): A new in-session UI exposes memory mode, individual memory deletion, and a reset button. Memory reset now preserves past rollouts rather than invalidating them, so resetting clears the future recall surface without breaking session replay.⁸²

Memory vs AGENTS.md

Tip: Use /m_update for facts that should persist indefinitely. For session-specific context, just tell Codex directly in the conversation. For shared team context, use AGENTS.md.

Session Management

Codex persists sessions under ~/.codex/sessions/, enabling resume, forking, and multi-thread workflows across CLI and desktop surfaces.

Resume

Pick up where you left off:

codex resume                          # Interactive picker (sorted by recency)
codex resume <SESSION_ID>             # Resume a specific session
codex exec resume --last "continue"   # Non-interactive: resume most recent

The /resume slash command inside the TUI opens the same interactive picker with search.

Fork

Branch a conversation 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 sharing the same history up to the fork point. Changes in one fork don’t affect the other. This is useful for comparing approaches (e.g., “fork and try Redis instead of Memcached”) or exploring risky changes safely.

Thread forking into sub-agents (v0.107.0): Threads can now be forked into independent sub-agents, allowing a conversation to spawn parallel work streams that execute autonomously. This extends the existing fork model — instead of just branching the conversation, the forked thread becomes a sub-agent with its own execution context.⁶² As of v0.117.0, sub-agents use path-based addresses (e.g., /root/agent_a) with structured inter-agent messaging, making multi-agent coordination more explicit and debuggable.⁷⁵

Thread Listing

View and manage active sessions:

/status                            # Current session info and token usage
/ps                                # Show background terminals in session

In the desktop app, threads are visible in the sidebar with full history and diff previews.

Session Lifecycle

Sessions sync between CLI and desktop app — start in one, continue in 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 --sandbox workspace-write --ask-for-approval on-request "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. The design 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 exec startup banner (v0.130.0). The codex exec startup banner no longer prints the legacy “research preview” wording. If your CI scrapes startup output, the banner text is now slimmer; structured --json events are unchanged.⁹¹

codex remote-control (v0.130.0+)

codex remote-control is a top-level command that starts a headless app-server intended to be driven by another process — IDE extensions, custom orchestrators, or remote control planes. It replaces the multi-flag codex app-server invocation many integrators were stitching together by hand and gives third-party tooling a single, stable entrypoint into the same app-server runtime that ships under the desktop and IDE surfaces.⁹¹

# Start a headless, remotely controllable app-server
codex remote-control

# Same lifecycle as a TUI session: thread store, hooks, plugins, MCP, sandbox
# all initialize from your normal config.toml.

Pair codex remote-control with the app-server pagination APIs below when you are building UIs that need to enumerate large thread histories without hydrating every turn into memory at once.

App-Server Thread Pagination (v0.130.0+)

App-server clients can now page large threads through three distinct turn item views:⁹¹

Pair pagination with the ThreadStore interface introduced in v0.121.0 to walk long-running threads efficiently, especially in remote-control deployments where the orchestrator may be on a different machine than the rollout files.⁸²

Live App-Server Config Refresh (v0.130.0+)

Live app-server threads now pick up config.toml changes without requiring a restart — edit the config, save, and the running thread reflects the new values on its next turn. This is the bug-fix counterpart to codex remote-control: a long-running headless server can be reconfigured in place rather than torn down.⁹¹

Codex Cloud & Background Tasks [EXPERIMENTAL]

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

Codex Cloud runs tasks asynchronously in OpenAI-managed environments.⁴ See also GitHub Action & CI/CD for integrating Codex into your CI pipeline.

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 and Windows) provides a graphical interface optimized for multi-project management.¹⁶ The Windows version launched on March 4, 2026 with native PowerShell support and native Windows sandbox.⁶⁶

Installation

codex app                      # Auto-downloads and installs on first run

Or download directly: Codex.dmg (macOS) | Available in the Microsoft Store (Windows)

Key Features

Thread Modes

Each thread runs in one of three modes, selected when you create it:

Worktree isolation mechanics:

When you start a Worktree thread, the desktop app: 1. Creates a new git worktree (git worktree add) in a temporary directory 2. Checks out a fresh branch from your current HEAD 3. Runs the agent inside the worktree — all file changes are isolated 4. Presents a diff review when done — you choose which changes to merge back

This means multiple Worktree threads can run simultaneously on the same repo without conflicts. Each gets its own branch and working directory.

Automations

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

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

Setting up an automation: 1. Open a project in the desktop app 2. Click the Automations tab in the sidebar 3. Define a trigger (schedule, webhook, or manual) 4. Write the prompt and select execution mode (local or worktree) 5. Set the reasoning level for the automation run (App v26.312)⁷² 6. Automations run on schedule and queue results for review

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

The Codex Desktop App launched on Windows on March 4, 2026 (App v26.304) with native PowerShell support, native Windows sandbox, and full feature parity including skills, automations, and worktrees without requiring WSL.⁶⁶

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, the 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: "..." })
• Image workflows (v0.117.0): view_image returns URLs, generated images are reopenable, and image history survives session resume⁷⁵
• Multi-environment view_image (v0.130.0): For sessions that span multiple environments (introduced in v0.124.0 with per-turn environment + working-directory selection, refined in v0.125.0 with sticky environments), view_image now resolves file paths through the selected environment rather than the orchestrator’s local filesystem. An image attached from a remote environment is fetched relative to that environment’s working directory, not the host running the SDK.⁹¹

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.5" },
});

Sessions persist under ~/.codex/sessions.

Runtime: Node.js 18+.

Performance Optimization

Context Management

Context windows vary by model. As of April 2026: GPT-5.5 in Codex offers 400K (1M in the API). GPT-5.4 / GPT-5.4-mini offer 1M / 400K respectively (API-equivalent in Codex). The GPT-5.3-Codex / GPT-5.2-Codex family runs on a 272K input + 128K output (400K total budget). All of them fill faster than you’d expect — 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, so 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

Error Messages Reference

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

Codex Security [PREVIEW]

Codex Security entered research preview on March 6, 2026, bringing context-aware application security review into the Codex stack.⁷⁷ Available to ChatGPT Pro, Enterprise, Business, and Edu customers via Codex web.

How it works: Codex Security analyzes repositories to build a project-specific threat model, identifies vulnerabilities classified by real-world impact, and pressure-tests findings in a sandboxed environment to validate them. The agent surfaces higher-confidence findings with fixes, reducing noise from insignificant bugs.

Performance: During research preview, Codex Security scanned 1.2 million commits and identified 10,561 high-severity vulnerabilities. Precision improved over time — cutting noise by 84%, reducing over-reported severity by 90%+, and halving false positive rates. The system has found real vulnerabilities in OpenSSH, GnuTLS, and Chromium, with 14 CVEs assigned.⁷⁷

Note: Codex Security is separate from the CLI’s built-in sandbox security model. The sandbox protects your machine from Codex; Codex Security protects your codebase from vulnerabilities.

Enterprise Deployment

Admin Controls (requirements.toml)

Administrators enforce enterprise policy 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", "never"]

# 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 that 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. Set the standard environment variables before launching Codex:

# Point Codex at your OTel collector
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otel-collector.internal:4318"
export OTEL_SERVICE_NAME="codex-cli"
export OTEL_RESOURCE_ATTRIBUTES="team=platform,env=production"

# Launch Codex — trace context propagates to all OpenAI API calls
codex

• Standard OTEL_* environment variables are respected (endpoint, service name, resource attributes)
• Trace context propagates through Codex to API calls, enabling end-to-end observability
• Use resource attributes to tag traces by team, environment, or project
• Keep privacy requirements in mind when enabling prompt/tool logging — traces may contain code snippets
• Configurable OpenTelemetry trace metadata (v0.130.0+). Beyond the standard OTEL_RESOURCE_ATTRIBUTES envelope, the codex-otel crate now exposes configurable trace metadata so administrators can tag traces with organization-specific dimensions (cost-center, project ID, ticket reference) without rebuilding OTEL_RESOURCE_ATTRIBUTES from scratch on every invocation. Pair this with the richer review/feedback analytics shipped in the same release for unified debugging and triage across CLI, app-server, and remote-control sessions.⁹¹

Enterprise Access

• ChatGPT Business / Enterprise / Edu: Org-admin controlled access, with cloud-fetched requirements applied automatically. Supports SSO via SAML/OIDC through your identity provider (Okta, Entra ID, etc.)
• API: Standard API auth, billing, and org/project controls. OpenAI publishes SOC 2 Type II and SOC 3 reports; HIPAA BAA available for Enterprise tier
• 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

Data handling and compliance: - API inputs/outputs are not used for training under OpenAI’s Business/Enterprise/API terms - For data residency, OpenAI API traffic routes through US-based infrastructure by default; for EU data residency requirements, consult OpenAI’s Enterprise sales team - Session transcripts are stored locally; only API calls leave the machine - ChatGPT Enterprise supports compliance frameworks including SOC 2, GDPR, and CCPA

Rollout Strategy

Recommended phased rollout for organizations:

1. Pilot (Week 1-2): Deploy to 3-5 senior engineers with requirements.toml enforcing untrusted sandbox mode and cached web search. Collect feedback on AGENTS.md patterns and MCP server needs.
2. Team expansion (Week 3-4): Roll out to full team. Distribute team-standard config.toml via MDM or repo. Enable workspace-write sandbox for trusted repositories.
3. CI integration (Week 5-6): Add codex-action to CI/CD pipelines for automated PR review and test generation. Use --ephemeral to keep costs predictable.
4. Org-wide (Month 2+): Deploy via MDM with requirements.toml enforcing approved MCP servers, sandbox policies, and model allowlists.

Audit Patterns

Track Codex usage and enforce compliance:

• OpenTelemetry traces: Monitor API call volume, token usage, and latency per team
• Session persistence: Audit ~/.codex/sessions/ for compliance review (disable with --ephemeral in sensitive contexts)
• MCP identity enforcement: requirements.toml logs blocked server attempts — review for unauthorized tool usage
• Git audit trail: All Codex file changes go through standard git — review via branch history and PR diffs

Best Practices & Anti-Patterns

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, since 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 community-maintained 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

Anti-Patterns

Common mistakes that waste tokens, produce poor results, or create frustrating workflows.

Cost Anti-Patterns

Context Anti-Patterns

Workflow Anti-Patterns

Prompt Anti-Patterns

Workflow Recipes

End-to-end patterns for common development scenarios.

Recipe 1: New Project Setup

mkdir my-app && cd my-app && git init
codex

> Create a FastAPI project with: main.py, requirements.txt, Dockerfile,
  basic health endpoint, and a README. Use async throughout.

> /init

Review the generated AGENTS.md, edit to match your conventions, then:

> Run the health endpoint test and confirm it passes

Recipe 2: Daily Development Flow

cd ~/project && git checkout -b feature/user-auth
codex

> @src/models/user.py @src/api/auth.py
  Add password reset functionality. Requirements:
  1. POST /api/auth/reset-request (email → sends token)
  2. POST /api/auth/reset-confirm (token + new password)
  3. Tests for both endpoints
  Run tests when done.

Review with /diff, then commit.

Recipe 3: Complex Refactor with Plan Mode

codex

> /plan Migrate the database layer from raw SQL to SQLAlchemy ORM.
  Constraints: don't change any API contracts, keep all existing tests passing.

Review the plan. Approve or steer:

[Tab] Also add a migration script using Alembic

After Codex executes, verify:

> Run the full test suite and report results
> /diff

Recipe 4: PR Review with codex exec

codex exec --model gpt-5.1-codex-mini \
  "Review the changes in this branch against main. \
   Flag security issues, missed edge cases, and style violations. \
   Format as a markdown checklist." \
  -o review.md

Recipe 5: Debugging with Cloud Tasks [EXPERIMENTAL]

codex cloud exec --env my-env "Diagnose why the /api/orders endpoint returns 500 \
  for orders with > 100 line items. Check the serializer, database query, \
  and pagination logic. Propose a fix with tests."

Check progress later:

codex cloud status <TASK_ID>
codex cloud diff <TASK_ID>

Apply the fix locally when done:

codex apply <TASK_ID>

Migration Guide

From Claude Code

Key differences to understand:

• Sandbox is OS-level: Codex uses Seatbelt/Landlock, not containers. Restrictions operate at the kernel level, below the application layer.
• Hooks are expanding: Codex now supports 5 hook events: SessionStart, Stop, and UserPromptSubmit (v0.114.0–v0.116.0, experimental) plus AfterAgent (v0.99.0) and AfterToolUse (v0.100.0). The system covers session lifecycle, prompt interception, and tool-level automation, though Claude Code’s 12+ lifecycle events still offer broader coverage. For automation patterns not yet covered, use AGENTS.md instructions or skills.
• Sub-agents v2 (v0.117.0): Sub-agents now use path-based addresses (e.g., /root/agent_a) with structured inter-agent messaging and agent listing.⁷⁵ This extends the existing machinery (max 6 concurrent, reduced from 12 in v0.91.0). Multi-agent roles remain customizable via config (v0.104.0+).⁴⁷ v0.105.0 added spawn_agents_on_csv for fanout across rows with progress tracking and ETA.⁶¹ Codex still lacks Claude Code’s explicit Task tool UX for user-directed delegation — use cloud tasks or SDK orchestration for delegation patterns.
• AGENTS.md is cross-tool: Your AGENTS.md works in Cursor, Copilot, Amp, Jules, Gemini CLI, and 60,000+ open source projects. 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: - OS-level sandboxing (Seatbelt/Landlock — kernel-enforced vs container-based) - Cloud task delegation with codex apply - Config profiles for workflow switching - Desktop app with worktree isolation

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                   ║
║  --ask-for-approval <p>     Approval policy                   ║
║  --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   /goal        Persisted goal      ║
║  /vim          Modal Vim     /hooks       Browse/toggle hooks ║
║  /init         AGENTS.md scaffold                             ║
║  /mcp          MCP tools     /skills      Invoke skills       ║
║  /ps           Background    /personality Style               ║
║  /permissions  Approval mode /statusline  Footer config       ║
║  /fast         Toggle fast mode (default: on)                ║
║  /copy         Copy last response to clipboard                ║
║  /clear        Clear screen  /theme       Syntax highlighting ║
║                                                               ║
║  TUI SHORTCUTS                                                ║
║  @              Fuzzy file search                             ║
║  !command       Run shell command                             ║
║  Ctrl+G         External editor                               ║
║  Ctrl+L         Clear screen                                  ║
║  Enter          Inject instructions (while running)           ║
║  Esc Esc        Edit previous messages                        ║
║                                                               ║
║  EXEC MODE (CI/CD)                                            ║
║  codex exec --sandbox workspace-write "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               ║
║                                                               ║
║  PLUGINS                                                      ║
║  codex plugin marketplace add <src>     Add marketplace       ║
║  codex plugin marketplace upgrade       Upgrade marketplaces  ║
║                                                               ║
║  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-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (April 2026)                                          ║
║  gpt-5.5               Recommended default (400K in Codex)   ║
║  gpt-5.5-pro           Highest-effort GPT-5.5 tier            ║
║  gpt-5.4               Prior flagship / fallback              ║
║  gpt-5.4-mini          Subagent work, 2x faster (400K)        ║
║  gpt-5.3-codex         Legacy coding specialist               ║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

Changelog

References

Note on OpenAI blog URLs: References ¹⁶, ²⁵–³⁰, ³³, ⁶⁴, ⁶⁶, ⁶⁷, ⁷⁶, and ⁷⁷ link to openai.com/index/ blog posts which return HTTP 403 to automated access due to Cloudflare bot protection. These URLs are valid when accessed via a standard web browser.