Codex CLI: The Definitive Technical Reference

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 272K token budget, and AGENTS.md for cross-tool project instructions that work in Codex, Cursor, Amp, and more.

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

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

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

I spent months running Codex alongside Claude Code across production codebases, CI/CD pipelines, and team workflows. This guide distills that experience into the 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] are subject to change between releases. Codex Cloud and the MCP command group are both experimental as of v0.104.0. Core CLI, sandbox, AGENTS.md, config.toml, and Skills are stable.

Key Takeaways

• Four surfaces, one brain: CLI, desktop app, IDE extension, and cloud tasks all share the same GPT-5.x-Codex intelligence, 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.
• 272K input context fills fast: 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         │    │
│  └─────────────────────────────────────────────────┘    │
│  Shared model across all surfaces; costs tokens          │
└─────────────────────────────────────────────────────────┘

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

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

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

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

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

Table of Contents

1. How Do I Install Codex?
2. 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. JavaScript REPL Runtime
13. What Are Skills?
14. Plan Mode & Collaboration
15. Memory System
16. Session Management
17. Non-Interactive Mode (codex exec)
18. Codex Cloud & Background Tasks
19. The Codex Desktop App
20. GitHub Action & CI/CD
21. Codex SDK
22. Performance Optimization
23. How Do I Debug Issues?
24. Enterprise Deployment
25. Best Practices & Anti-Patterns
26. Workflow Recipes
27. Migration Guide
28. Quick Reference Card
29. Changelog
30. References

How Do I Install Codex?

Package Managers

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

# Homebrew (macOS)
brew install --cask codex

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

Binary Downloads

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

System Requirements

• macOS: Apple Silicon or Intel (full sandbox support via Seatbelt)
• Linux: x86_64 or arm64 (sandbox via Landlock + seccomp)
• Windows: 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.3-codex      # Specify model
codex --full-auto            # Workspace-write sandbox + on-request approval

The terminal UI is a full-screen application with:

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

Key TUI shortcuts:

Slash commands available in the TUI:

2. Codex Desktop App (macOS)

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

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

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

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

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

The Codex IDE extension integrates directly into your editor:

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

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

4. Codex Cloud [EXPERIMENTAL]

Cloud tasks run asynchronously in OpenAI-managed environments:

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

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

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

Configuration System Deep Dive

Codex uses TOML for configuration. Understanding the precedence hierarchy is critical 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.3-codex"                # Default model (272K input context)
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.2-codex"         # Model for /review command
oss_provider = "lmstudio"              # lmstudio|ollama (used with --oss)

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

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

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

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

# ─── Shell Environment ─────────────────────────────────
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+)
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.3-codex"
model_reasoning_effort = "xhigh"
approval_policy = "untrusted"
sandbox_mode = "read-only"

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

Activate a profile:

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

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

Custom Model Providers

Connect to Azure, local models, or proxy services:

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

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

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.2-codex" "refactor the API"
codex -c 'sandbox_workspace_write.network_access=true' "install dependencies"
codex -c model_reasoning_effort="xhigh" "debug the race condition"

Which Model Should I Choose?

Available Models (February 2026)

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

Model Selection Flowchart

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

Reasoning Effort

Control how much the model “thinks” before responding:

Supported levels are model-dependent. 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.

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:⁵³

Promotional rates: Free/Go access and 2x rate limits for paid plans coincided with the Codex Desktop App launch (February 2026). These higher limits apply across all surfaces — app, CLI, IDE, and cloud. OpenAI has not announced an end date.¹⁷

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⁶
• 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)⁷
• Windows: Native sandbox with restricted tokens (promoted from experimental in v0.100.0). WSL also supported (inherits Linux Landlock + seccomp)

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

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:

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

The --full-auto Flag

--full-auto is a convenience alias for:

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

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

Recommended Configurations

Daily development (safe default):

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

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

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

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"

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 --full-auto -- ls /etc/passwd   # macOS test
codex sandbox linux --full-auto -- cat /etc/shadow   # Linux test

If the sandbox is working correctly, both commands should fail with a permission denied error — the sandbox prevents reading sensitive system files even in --full-auto mode. 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"

Deep Dive: Anti-patterns that get ignored, patterns that work, and cross-tool compatibility for AGENTS.md files

Hooks

Codex added hooks in v0.99.0 (AfterAgent) and v0.100.0 (AfterToolUse). The hook system is early-stage compared to Claude Code’s 12+ lifecycle events but provides automation entry points for common workflows.

Available Hook Events

Hook Configuration

Hooks are configured in .codex/config.toml:

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

Replicating Claude Code Hook Patterns

If migrating from Claude Code, here’s how to achieve similar automation without the full hook event set:

Expert tip: The hook system is actively expanding. Check the Codex changelog for new hook events in each release.

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

Configuring MCP Servers

STDIO servers (local processes):

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

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

HTTP servers (remote):

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

CLI Management

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

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

Running Codex AS an MCP Server

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

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

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

JavaScript REPL Runtime [EXPERIMENTAL]

Codex v0.100.0 added an experimental, feature-gated JavaScript REPL runtime (js_repl) that persists state across tool calls. When enabled, Codex can execute JavaScript expressions and maintain variables, objects, and functions between calls within the same session.

Enabling the JS REPL:

# In config.toml
[features]
js_repl = true

Example usage: When enabled, Codex can maintain state across tool calls within a session:

// Codex can accumulate data across multiple tool calls
const results = await fetchTestResults();
const failures = results.filter(r => r.status === "failed");
console.log(`${failures.length} failures out of ${results.length} tests`);
// Variable 'failures' persists and is available in subsequent tool calls

This feature is experimental and feature-gated. The interface may change between releases.

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

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.

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)

• 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

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 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 --full-auto "fix the CI failure"
codex exec --json "triage open bugs" -o result.txt

By default, codex exec writes progress/events to stderr and the final agent message to stdout. 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 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 only, Apple Silicon) provides a graphical interface optimized for multi-project management.¹⁷

Installation

codex app                      # Auto-downloads and installs on first run

Or download directly: Codex.dmg

Key Features

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 the thread mode 5. 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

Windows support is planned. Check the Codex Desktop App page or GitHub releases for availability updates.¹⁸

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: "..." })

Thread and Client Configuration

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

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

Sessions persist under ~/.codex/sessions.

Runtime: Node.js 18+.

Performance Optimization

Context Management

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

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

Token Efficiency

Speed Optimization

1. gpt-5.3-codex-spark: Lower-latency variant for interactive pairing
2. --profile fast: Pre-configured mini model with low reasoning
3. Parallel tool execution: Codex runs independent reads/checks concurrently, 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.¹

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", "on-failure"]

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

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

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

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

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

Unlike user-level config.toml which sets preferences, requirements.toml is a hard constraint layer 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

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 nascent: Codex added hooks in v0.99.0 (AfterAgent) and v0.100.0 (AfterToolUse), but the system is early-stage compared to Claude Code’s 12+ lifecycle events. For automation patterns not yet covered, use AGENTS.md instructions or skills.
• Sub-agents are internal but now configurable: Codex has sub-agent machinery (max 6 concurrent, reduced from 12 in v0.91.0). As of v0.104.0, multi-agent roles are customizable via config, allowing named agent roles with distinct profiles.⁴⁹ 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                   ║
║  --full-auto                workspace-write + on-request      ║
║  --oss                      Use local models (Ollama)         ║
║  --search                   Enable live web search            ║
║                                                               ║
║  SLASH COMMANDS (in TUI)                                      ║
║  /compact      Free tokens   /diff        Git diff            ║
║  /review       Code review   /plan        Plan mode           ║
║  /model        Switch model  /status      Session info        ║
║  /fork         Fork thread   /init        AGENTS.md scaffold  ║
║  /mcp          MCP tools     /skills      Invoke skills       ║
║  /ps           Background    /personality Style               ║
║  /permissions  Approval mode /statusline  Footer config       ║
║                                                               ║
║  TUI SHORTCUTS                                                ║
║  @              Fuzzy file search                             ║
║  !command       Run shell command                             ║
║  Ctrl+G         External editor                               ║
║  Enter          Inject instructions (while running)           ║
║  Esc Esc        Edit previous messages                        ║
║                                                               ║
║  EXEC MODE (CI/CD)                                            ║
║  codex exec --full-auto "task"          Sandboxed auto        ║
║  codex exec --json -o out.txt "task"    JSON + file output    ║
║  codex exec --output-schema s.json      Structured output     ║
║  codex exec resume --last "continue"    Resume session        ║
║                                                               ║
║  MCP MANAGEMENT [EXPERIMENTAL]                                ║
║  codex mcp add <name> -- <cmd>    Add STDIO server            ║
║  codex mcp add <name> --url <u>   Add HTTP server             ║
║  codex mcp list                    List servers                ║
║  codex mcp login <name>           OAuth flow                  ║
║  codex mcp remove <name>          Delete server               ║
║                                                               ║
║  CLOUD [EXPERIMENTAL]                                         ║
║  codex cloud exec --env <ID> Start cloud task                 ║
║  codex cloud status <ID>     Check task progress              ║
║  codex cloud diff <ID>       View task diff                   ║
║  codex cloud list            List tasks                       ║
║  codex apply <TASK_ID>       Apply cloud diff locally         ║
║                                                               ║
║  CONFIG FILES                                                 ║
║  ~/.codex/config.toml        User config                      ║
║  .codex/config.toml          Project config                   ║
║  ~/.codex/AGENTS.md          Global instructions              ║
║  AGENTS.md                   Project instructions             ║
║  requirements.toml           Enterprise policy constraints    ║
║                                                               ║
║  SANDBOX MODES                                                ║
║  read-only          Read files only, no mutations             ║
║  workspace-write    Read/write in workspace + /tmp            ║
║  danger-full-access Full machine access                       ║
║                                                               ║
║  APPROVAL POLICIES                                            ║
║  untrusted     Prompt for all mutations                       ║
║  on-failure    Auto-run until failure                         ║
║  on-request    Prompt for boundary violations                 ║
║  never         No prompts                                     ║
║                                                               ║
║  MODELS (Feb 2026)                                            ║
║  gpt-5.3-codex         Default flagship (272K in / 400K)     ║
║  gpt-5.3-codex-spark   Interactive, lower latency (128K)     ║
║  gpt-5.2-codex         Long-horizon refactors (272K / 400K)  ║
║  gpt-5.1-codex-mini    Quick tasks, cost-efficient (272K/400K)║
║                                                               ║
╚═══════════════════════════════════════════════════════════════╝

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.