codex-cli

• Working with OpenAI models (GPT-5.2, GPT-5.1-Codex-Max, o3, o4-mini)
• Code generation and refactoring with latest models
• Git-aware workflows and PR reviews
• Full automation with permission bypass
• Reasoning-first development (o3 models, GPT-5.2 with xhigh reasoning)
• Multimodal tasks (code + images)
• Sandboxed execution environments
• Long-context tasks (400K tokens with GPT-5.2)

1. Install Codex CLI

```bash

# Check current installation

codex --version

# Install/Update globally via NPM

npm install -g @openai/codex

# Or use Homebrew (macOS/Linux)

brew install openai/tap/codex-cli

```

2. Setup Authentication

#### Option A: ChatGPT Plus/Pro (Recommended)

```bash

# Login with ChatGPT account

codex login

# Opens browser for OAuth authentication

# Includes GPT-5-Codex access with subscription

```

#### Option B: API Key

```bash

# Set OpenAI API key

export OPENAI_API_KEY="your-api-key-here"

# Or create config file

mkdir -p ~/.codex

echo 'api_key = "your-api-key-here"' > ~/.codex/config.toml

```

3. Basic Usage

```bash

# Direct execution (like gemini -p)

codex exec "Analyze this codebase and suggest improvements"

# Full automation (BYPASS ALL APPROVALS)

codex exec --dangerously-bypass-approvals-and-sandbox "Refactor authentication module"

# Safe automation (sandboxed)

codex exec --full-auto "Generate tests for all functions"

# Interactive mode

codex "Let's work on improving this code"

# With specific model (December 2025)

codex exec -m gpt-5.2 "Complex task with latest model"

codex exec -m gpt-5.1-codex-max "Best for agentic coding (default)"

codex exec -m o3 "Deep reasoning task"

codex exec -m o4-mini "Quick code generation"

```

--dangerously-bypass-approvals-and-sandbox - Complete automation, zero friction:

✅ When to Use Bypass Mode

```bash

# Trusted, repeatable workflows

codex exec --dangerously-bypass-approvals-and-sandbox "Add JSDoc comments to all ./src functions"

# Automated testing workflows

codex exec --dangerously-bypass-approvals-and-sandbox "Run tests and auto-fix all failures"

# Bulk operations

codex exec --dangerously-bypass-approvals-and-sandbox "Convert all .js files to TypeScript"

# CI/CD pipelines (externally sandboxed)

codex exec --dangerously-bypass-approvals-and-sandbox "Deploy to staging environment"

```

⚠️ Safer Automation Options

```bash

# --full-auto: Sandboxed with workspace write access

codex exec --full-auto "Refactor module safely"

# Custom approval + sandbox

codex exec -a never -s workspace-write "Controlled automation"

# On-failure approval (runs until error)

codex exec -a on-failure "Try operations, escalate on error"

```

Approval Policies

```bash

# -a never: Full automation (no approvals)

codex exec -a never "Complete workflow automation"

# -a on-request: Model decides when to ask

codex exec -a on-request "Intelligent approval requests"

# -a on-failure: Only ask if command fails

codex exec -a on-failure "Run until failure, then ask"

# -a untrusted: Only run trusted commands (default)

codex exec -a untrusted "Safe, limited automation"

```

Sandbox Modes

```bash

# -s read-only: Cannot modify files

codex exec -s read-only "Analysis only, no changes"

# -s workspace-write: Can modify workspace

codex exec -s workspace-write "Safe file modifications"

# -s danger-full-access: Full system access

codex exec -s danger-full-access "Complete control (use carefully)"

```

GPT-5.2 Series (NEW - December 11, 2025)

```bash

# GPT-5.2 Thinking - Latest frontier model

# 400K context, 128K output, knowledge cutoff Aug 31, 2025

# Pricing: $1.75/1M input, $14/1M output (90% cached discount)

codex exec -m gpt-5.2 "Complex multi-step task with deep reasoning"

# GPT-5.2 Instant - Speed optimized for routine queries

codex exec -m gpt-5.2-chat-latest "Fast information seeking and writing"

# GPT-5.2 Pro - Maximum accuracy (Responses API only)

# Pricing: $21/1M input, $168/1M output

# Supports reasoning.effort: medium, high, xhigh

codex exec -m gpt-5.2-pro "Critical high-accuracy tasks"

```

GPT-5.1 Codex Series (Recommended for Coding)

```bash

# GPT-5.1-Codex-Max - DEFAULT for Codex CLI

# Best for agentic coding with native compaction support

codex exec -m gpt-5.1-codex-max "Complex development workflows"

# GPT-5.1-Codex - Optimized for long-running agentic tasks

codex exec -m gpt-5.1-codex "Extended coding sessions"

# GPT-5.1-Codex-Mini - Cost-efficient coding

codex exec -m gpt-5.1-codex-mini "Quick code tasks"

```

Legacy GPT-5 Series

```bash

# GPT-5 - General model (use GPT-5.2 for latest)

codex exec -m gpt-5 "General tasks"

# GPT-5-Codex - Previous coding model

codex exec -m gpt-5-codex "Code generation"

```

o-Series (Reasoning Models)

```bash

# o3 - Smartest reasoning model

codex exec -m o3 "Complex architectural decisions"

# o4-mini - Efficient reasoning

codex exec -m o4-mini "Quick reasoning tasks"

```

New GPT-5.2 Features

```bash

# Extended reasoning with xhigh effort (GPT-5.2 Pro/Thinking)

codex exec -m gpt-5.2-pro --reasoning-effort xhigh "Maximum accuracy task"

# Context compaction for long sessions

codex exec -m gpt-5.2 --compact "Long document analysis"

# Concise reasoning summaries

codex exec -m gpt-5.2 --concise-reasoning "Explain this code"

```

Claude orchestrates, Codex executes - The Think-Act-Observe Loop:

Structured Workflows

```bash

#!/bin/bash

# Claude directs Codex for complete feature development

# THINK: Claude analyzes requirements

echo "Goal: Add user profile caching"

# ACT: Codex researches best practices (with web search)

codex exec --search --dangerously-bypass-approvals-and-sandbox \

"Research Redis caching patterns and create implementation plan" \

> plan.md

# OBSERVE: Claude reviews the plan

cat plan.md

# ACT: Codex implements (full automation)

codex exec --dangerously-bypass-approvals-and-sandbox --json \

"Implement the caching system according to @plan.md" \

> implementation.json

# OBSERVE: Claude verifies

jq '.changes[]' implementation.json

# ACT: Codex tests

codex exec --dangerously-bypass-approvals-and-sandbox \

"Generate and run comprehensive tests"

# Loop continues...

```

JSON Output for AI Parsing

```bash

# Get structured output for Claude to parse

codex exec --json "List all exported functions in ./src" > functions.json

# Claude processes reliably

for func in $(jq -r '.functions[].name' functions.json); do

echo "Processing: $func"

codex exec --dangerously-bypass-approvals-and-sandbox \

"Add input validation to $func function"

done

```

Sequential Task Decomposition

```bash

#!/bin/bash

# Claude breaks down complex goal into safe atomic steps

echo "=== Feature: Add OAuth2 Authentication ==="

# Step 1: Research (safe, read-only)

codex exec --search --full-auto "Research OAuth2 best practices 2025" > research.md

# Step 2: Plan (Claude reviews)

codex exec "Create detailed OAuth2 implementation plan based on @research.md"

read -p "Review plan. Continue? [y/N] " -r

# Step 3: Install dependencies

codex exec --dangerously-bypass-approvals-and-sandbox "Install OAuth2 packages"

# Step 4: Generate code

codex exec --dangerously-bypass-approvals-and-sandbox \

"Generate OAuth2 auth module according to plan"

# Step 5: Tests

codex exec --dangerously-bypass-approvals-and-sandbox \

"Generate comprehensive OAuth2 tests"

# Step 6: Verify

codex exec --dangerously-bypass-approvals-and-sandbox "Run all tests and fix failures"

```

Web Search Integration

```bash

# Enable web search for research

codex exec --search --dangerously-bypass-approvals-and-sandbox \

"Research latest React 19 features and create migration guide"

# Research-driven development

codex exec --search --full-auto \

"Find best practices for microservices and implement API gateway"

```

Multimodal (Code + Images)

```bash

# Attach design screenshots

codex exec -i design.png --dangerously-bypass-approvals-and-sandbox \

"Implement this UI design in React"

# Multiple images

codex exec -i mockup1.png -i mockup2.png --full-auto \

"Compare these designs and implement the better approach"

```

Git-Aware Workflows

```bash

# Apply Codex changes as git patch

codex apply

# or

codex a

# Work on git branch

git checkout -b feature/new-auth

codex exec --dangerously-bypass-approvals-and-sandbox \

"Implement authentication with clean commits"

# Codex respects .gitignore and git history

```

Resume Sessions

```bash

# Resume last session

codex exec resume --last

# Pick from previous sessions

codex resume

```

Configuration Profiles

```bash

# Create profile in ~/.codex/config.toml

[profiles.auto-dev]

model = "gpt-5.1-codex"

ask_for_approval = "never"

sandbox = "workspace-write"

search = true

# Use profile

codex exec -p auto-dev "Develop new feature automatically"

```

MCP Server Integration

```bash

# Run as MCP server

codex mcp

# Manage MCP servers (experimental)

codex mcp list

codex mcp add

```

Automated Code Generation

```bash

#!/bin/bash

# Complete automation for code generation

generate_api() {

local spec="$1"

codex exec --dangerously-bypass-approvals-and-sandbox \

--json \

--search \

"Read API specification @$spec and generate:

1. Data models with validation

2. API endpoints with OpenAPI docs

3. Database migrations

4. Comprehensive tests

5. Error handling middleware

6. Authentication middleware

7. Rate limiting

8. API documentation"

}

# Usage

generate_api "./specs/user-api.yaml"

```

Automated Refactoring

```bash

#!/bin/bash

# Safe, automated refactoring workflow

refactor_module() {

local module="$1"

# Backup first

git stash push -m "pre-refactor-$(date +%s)"

# Full automation with git safety

codex exec --dangerously-bypass-approvals-and-sandbox \

"Refactor $module:

1. Analyze current code structure

2. Identify improvements

3. Apply modern patterns

4. Add comprehensive tests

5. Run all tests

6. Fix any test failures

7. Update documentation

8. Create clean git commits"

if [ $? -eq 0 ]; then

echo "Refactoring complete!"

else

git stash pop

echo "Refactoring failed, restored backup"

fi

}

# Usage

refactor_module "./src/auth"

```

Test Generation & Fixing

```bash

#!/bin/bash

# Automated test generation and fixing

automate_testing() {

local target="$1"

codex exec --dangerously-bypass-approvals-and-sandbox \

"Complete testing workflow for $target:

1. Analyze code coverage gaps

2. Generate comprehensive unit tests

3. Generate integration tests

4. Generate end-to-end tests

5. Run all tests

6. Fix any failing tests

7. Achieve 100% coverage

8. Generate test report"

}

# Usage

automate_testing "./src"

```

CI/CD Integration

```yaml

# GitHub Actions with Codex

name: Codex Automation

on: [push, pull_request]

jobs:

codex-review:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v3

- name: Setup Node.js

uses: actions/setup-node@v3

with:

node-version: '20'

- name: Install Codex CLI

run: npm install -g @openai/codex

- name: Run Codex Analysis

env:

OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

run: |

codex exec --dangerously-bypass-approvals-and-sandbox \

--json \

"Analyze code changes, run tests, fix issues, generate report" \

> codex-report.json

- name: Upload Report

uses: actions/upload-artifact@v3

with:

name: codex-analysis

path: codex-report.json

```

Config File (~/.codex/config.toml)

```toml

# Default model (December 2025)

model = "gpt-5.1-codex-max" # Best for agentic coding

# Approval policy

ask_for_approval = "on-request" # or "never", "on-failure", "untrusted"

# Sandbox mode

sandbox = "workspace-write" # or "read-only", "danger-full-access"

# Enable web search

search = true

# Additional writable directories

add_dirs = ["./docs", "./tests"]

# Feature flags

[features]

web_search = true

multimodal = true

mcp = true

# Profiles for different workflows

[profiles.safe]

ask_for_approval = "untrusted"

sandbox = "read-only"

[profiles.auto]

ask_for_approval = "never"

sandbox = "workspace-write"

search = true

[profiles.danger]

ask_for_approval = "never"

sandbox = "danger-full-access"

search = true

# NEW: GPT-5.2 optimized profiles

[profiles.gpt52]

model = "gpt-5.2"

ask_for_approval = "never"

sandbox = "workspace-write"

search = true

[profiles.gpt52-pro]

model = "gpt-5.2-pro"

reasoning_effort = "xhigh"

ask_for_approval = "on-request"

sandbox = "workspace-write"

[profiles.long-context]

model = "gpt-5.2"

ask_for_approval = "never"

sandbox = "workspace-write"

compact = true # Enable context compaction

```

Environment Variables

```bash

# Authentication

export OPENAI_API_KEY="your-key"

# Default model (December 2025)

export CODEX_MODEL="gpt-5.1-codex-max" # For agentic coding

# export CODEX_MODEL="gpt-5.2" # For general tasks with 400K context

# export CODEX_MODEL="gpt-5.2-pro" # For maximum accuracy

# Default config path

export CODEX_CONFIG_PATH="~/.codex/config.toml"

# GPT-5.2 specific options

export CODEX_REASONING_EFFORT="high" # medium, high, xhigh

```

Security with Bypass Mode

When using --dangerously-bypass-approvals-and-sandbox:

1. Use in Controlled Environments

- CI/CD with external sandboxing

- Docker containers

- Disposable development environments

1. Always Have Backups

```bash

git stash push -m "pre-codex-$(date +%s)"

codex exec --dangerously-bypass-approvals-and-sandbox "task"

```

1. Use Git for Safety

- Work on feature branches

- Review diffs before pushing

- Use codex apply to review changes

1. Limit Scope

```bash

codex exec --dangerously-bypass-approvals-and-sandbox \

-C ./specific/directory \

"Only affect this directory"

```

Model Selection Strategy (December 2025)

```bash

# Quick tasks: o4-mini or gpt-5.1-codex-mini

codex exec -m o4-mini "Format code with Prettier"

codex exec -m gpt-5.1-codex-mini "Quick code fixes"

# Standard development: gpt-5.1-codex-max (DEFAULT)

codex exec -m gpt-5.1-codex-max "Implement user authentication"

# Long-context tasks: gpt-5.2 (400K context)

codex exec -m gpt-5.2 "Analyze entire codebase"

# Complex reasoning: o3 or gpt-5.2-pro with xhigh

codex exec -m o3 "Design scalable microservices architecture"

codex exec -m gpt-5.2-pro --reasoning-effort xhigh "Critical architecture decisions"

# Speed-optimized: gpt-5.2-chat-latest (Instant)

codex exec -m gpt-5.2-chat-latest "Quick information retrieval"

# Maximum accuracy: gpt-5.2-pro

codex exec -m gpt-5.2-pro "High-stakes production code"

```

Performance Optimization

```bash

# Use JSON for faster parsing

codex exec --json "task" | jq .

# Skip git checks if not needed

codex exec --skip-git-repo-check "task"

# Specify working directory

codex exec -C ./project "task"

# Use profiles to avoid repetitive flags

codex exec -p auto-dev "task"

```

Common Issues

Authentication Failed

```bash

codex logout

codex login

```

Model Not Available

```bash

# Check available models (December 2025)

codex exec -m gpt-5.2 "test" || echo "GPT-5.2 not available"

# Fall back to stable coding model

codex exec -m gpt-5.1-codex-max "task"

# Or use previous generation

codex exec -m gpt-5.1-codex "task"

```

Sandbox Errors

```bash

# Try different sandbox mode

codex exec -s danger-full-access "task"

# Or bypass entirely (if safe)

codex exec --dangerously-bypass-approvals-and-sandbox "task"

```

• codex-auth: Authentication and API key management
• codex-chat: Interactive REPL workflows
• codex-tools: Tool execution and file operations
• codex-review: Code review and git workflows
• codex-git: Git-aware development patterns

```bash

# Update Codex CLI

npm update -g @openai/codex

# Check version

codex --version

# Check for new models

codex exec "What models are available?"

```

---

Created for Claude Code - Full automation for AI-to-AI collaboration