Overview
OpenAI Codex CLI is a terminal-based AI coding assistant. It runs in a project directory and can read files, write code, run commands, and iterate based on test output.
Installation
npm install -g @openai/codex
# Verify
codex --version
Requires Node.js 18+.
Authentication
| Method | When | |--------|------| | ChatGPT login | Any ChatGPT subscription — browser OAuth redirect | | API key | No subscription, or programmatic access |
Plans: Go ($8/mo), Plus ($20/mo), Pro ($100–$200/mo). Pro recommended for fast mode and high reasoning tasks.
Commands Quick Reference
| Codex | Claude Code Equivalent | Description |
|-------|----------------------|-------------|
| codex | claude | Launch agent in current directory |
| codex --yolo | claude --dangerously-skip-permissions | Full access, no approval prompts |
| codex --model o3 | --model claude-opus-4-6 | Specify model |
| codex --quiet | n/a | Minimal output, automation-friendly |
Sandbox Modes
Codex runs in one of three modes, selected at startup:
| Mode | Behavior | When to Use |
|------|----------|-------------|
| suggest (default) | Proposes changes, you approve each | Unfamiliar codebase, learning |
| auto | Auto-applies low-risk changes, asks on risky ones | Day-to-day development |
| full (--yolo) | No approvals, runs everything | Trusted projects, CI environments |
Slash Commands
Codex supports slash commands in the interactive session:
/clear — clear conversation context
/history — show conversation history
/diff — show uncommitted changes
/files — list files in context
/model <name> — switch model mid-session
/quit — exit
Workflow Patterns
Pattern 1: Plan First, Then Build
codex "Create a plan for adding Stripe subscriptions to this Next.js app. \
List all files that need to change. Don't write code yet."
# Review the plan
codex "Execute the plan. Write all the code."
Pattern 2: Test-Driven Development
codex "Write tests for the UserService class first. \
Then implement the class to make them pass."
Pattern 3: Iterative Bug Fix
codex "Run the test suite and fix any failing tests. \
Keep running until all tests pass."
Pattern 4: Architecture Review
codex --quiet "Review the codebase structure and identify: \
1. Circular dependencies \
2. Missing error handling \
3. Security risks \
Output as a prioritized list."
Model Selection
codex --model o3 # Best reasoning
codex --model o4-mini # Fast, cost-efficient
codex --model gpt-4.1 # General purpose
Codex defaults to the model associated with your subscription tier. Pro subscribers get access to o3 and full context.
Context Management
Codex loads files from the current directory into context. To control what's loaded:
# Add specific files
codex "With context from src/auth/ and src/api/, refactor the auth middleware"
# Ignore patterns (via .codexignore or .gitignore)
echo "node_modules/" >> .codexignore
echo "*.log" >> .codexignore
Non-Interactive Mode
For CI pipelines and automation:
# Run single task, no prompts
codex --quiet --yolo "Run lint and fix all errors"
# With specific model
codex --quiet --model o4-mini "Generate TypeScript types from schema.sql"
Comparison: Codex vs Claude Code
| Feature | Codex | Claude Code | |---------|-------|-------------| | Underlying LLM | OpenAI GPT/o-series | Anthropic Claude | | Tool approval UI | Inline diffs | Interactive prompt | | Sub-agents | No | Yes (.claude/agents/) | | Skills system | No | Yes (.claude/skills/) | | Memory | Session only | Persistent (MEMORY.md) | | MCP support | No | Yes | | Hooks | No | Yes (PostToolUse, Stop) | | Best for | Code-heavy focused tasks | Orchestration, multi-step |
Agency Config (Codex Desktop)
Codex Desktop reads config from ~/.codex/ including agent definitions and skill references. Agents are loaded at startup and not hot-reloaded — restart required after config changes.