# Install globally with npm
npm install -g @openai/codex

# Install with Homebrew (macOS)
brew install --cask codex

# Install with pnpm (official monorepo manager)
pnpm install -g @openai/codex

# Update with npm
npm update -g @openai/codex

# Update with Homebrew
brew upgrade codex

# Windows: Use the install.ps1 script
# Download from: https://github.com/openai/codex/releases/latest
# Run: .\install.ps1

# Download binary from GitHub releases
# Visit: https://github.com/openai/codex/releases/latest

# Start interactive mode
codex

# Run with a specific prompt
codex "explain this project"

# Non-interactive execution
codex exec "explain utils.ts"

# Sign in with ChatGPT account (recommended)
codex
# Then select "Sign in with ChatGPT"

# Use API key (alternative - usage-based billing)
printenv OPENAI_API_KEY | codex login --with-api-key
# Or from a file:
codex login --with-api-key < my_key.txt

# Keyboard shortcuts
Ctrl+C                    # Cancel current operation
Ctrl+D                    # Exit Codex
Tab                       # Auto-complete
↑/↓                       # Command history
Esc Esc                   # Edit previous message

# Special input
@                         # Trigger file search (fuzzy find)

/model                    # Choose model and reasoning effort
/approvals                # Configure what Codex can do without approval
/review                   # Review current changes and find issues
/new                      # Start a new chat during conversation
/init                     # Create an AGENTS.md file with instructions
/compact                  # Summarize conversation to prevent context limit
/diff                     # Show git diff (including untracked files)
/mention                  # Mention a file
/status                   # Show current session config and token usage
/mcp                      # List configured MCP tools
/logout                   # Log out of Codex
/quit                     # Exit Codex
/exit                     # Exit Codex
/feedback                 # Send logs to maintainers

# Codex can read, write, and edit files
"Read the contents of src/app.js"
"Create a new file called utils.js"
"Edit the function in main.py to add error handling"

# View project structure
"Explain the structure of this project"
"What files are in the src directory?"

# Code analysis
"Explain what this code does"
"Review this function for bugs"
"Suggest improvements for this file"

# Code generation
"Write a function to parse JSON"
"Create unit tests for this module"
"Add error handling to this code"

# Resume sessions
codex resume                          # Open session picker
codex resume --last                   # Resume most recent session
codex resume <SESSION_ID>             # Resume specific session by ID

# Non-interactive session resume
codex exec resume <SESSION_ID>        # Resume non-interactive session
codex exec resume --last              # Resume last non-interactive session

# Model selection
codex --model gpt-5 "your prompt"
codex -m o3 "complex task"

# Working directory
codex --cd /path/to/project           # Change working directory
codex -C ../other-project             # Short form

# Multiple directories
codex --add-dir ../backend --add-dir ../shared "analyze all"

# Approval settings
codex --ask-for-approval untrusted    # Ask for untrusted commands
codex -a on-failure                   # Ask on command failure

# Sandbox settings
codex --sandbox read-only             # Read-only sandbox (default)
codex --sandbox workspace-write       # Allow workspace writes
codex --sandbox danger-full-access    # Disable sandbox (dangerous!)

# Image input
codex -i screenshot.png "explain this error"
codex --image img1.png,img2.jpg "summarize these diagrams"

# Shell completions
codex completion bash                 # Generate bash completions
codex completion zsh                  # Generate zsh completions
codex completion fish                 # Generate fish completions

# Config file location: ~/.codex/config.toml

# Edit config manually or use CLI flags
codex --model gpt-5 "your prompt"
codex --config model="gpt-5"

# Common configurations in config.toml:
# - model selection
# - approval_policy
# - sandbox_mode
# - mcp_servers
# - profiles

# Set model in config.toml
model = "gpt-5.3-codex"            # Latest recommended (March 2026)
model = "gpt-5.4"                   # Newest model with advanced reasoning
model = "gpt-5"                     # Original GPT-5 (still available)

# For reasoning models (gpt-5.3-codex, gpt-5.4, gpt-5):
model_reasoning_effort = "medium"  # minimal, low, medium, high
model_reasoning_summary = "auto"   # auto, concise, detailed, none

# For GPT-5 family models:
model_verbosity = "medium"         # low, medium, high

# Models available (as of March 2026):
# - gpt-5.3-codex (default on macOS/Linux) - Latest Codex-optimized
# - gpt-5.4 (newest) - Advanced reasoning and accuracy
# - gpt-5.3-instant - Faster, smoother conversations
# - gpt-5 (legacy) - Original GPT-5
# - Other OpenAI models via custom providers

GPT-5.3 Updates (March 2026)

GPT-5.3 Instant brings smoother conversations with:

• Better judgment around refusals (fewer unnecessary caveats)
• More useful web-search answers (less link dumping)
• Natural conversational flow (no "Stop. Take a breath." preamble)
• 26.8% reduction in hallucinations with web use
• Stronger creative writing with more texture

GPT-5.3-Codex is the recommended model for Codex CLI:

• Optimized for code understanding and generation
• Better at following complex instructions
• Improved accuracy on technical tasks

See GPT-5.3 Instant announcement for details.

# Create custom prompts in ~/.codex/prompts/

# Example: Create ~/.codex/prompts/review.md
# Then use with:
"Use the review prompt on this code"

# Create AGENTS.md in project root
# Codex will remember project-specific context

# Example AGENTS.md content:
"""
This project uses:
- Node.js with Express
- PostgreSQL database
- Jest for testing

Coding standards:
- Use TypeScript
- Follow ESLint rules
- Write tests for all new features
"""

# Configure MCP servers in ~/.codex/config.toml

# STDIO server example
[mcp_servers.filesystem]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
env = { API_KEY = "value" }

# Streamable HTTP server example
[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_TOKEN"

# MCP CLI commands
codex mcp list                        # List configured servers
codex mcp add <name> -- <command>     # Add a server
codex mcp get <name>                  # Show server details
codex mcp remove <name>               # Remove a server
codex mcp login <name>                # OAuth login (streamable HTTP)
codex mcp logout <name>               # OAuth logout

# Popular MCP servers:
# - Context7 (developer documentation)
# - Figma (design access)
# - Playwright (browser control)
# - GitHub (GitHub API access)
# - Sentry (log access)

See MCP Documentation for details.

# Configure sandbox mode in config.toml
sandbox_mode = "read-only"              # Default: read-only
sandbox_mode = "workspace-write"        # Allow writes in workspace
sandbox_mode = "danger-full-access"     # Disable sandbox (dangerous!)

# Configure approval policy
approval_policy = "untrusted"           # Prompt for untrusted commands
approval_policy = "on-failure"          # Prompt on command failure
approval_policy = "on-request"          # Model decides when to ask
approval_policy = "never"               # Never prompt (exec default)

# Workspace-write options
[sandbox_workspace_write]
writable_roots = ["/path/to/extra/dir"]
network_access = false
exclude_tmpdir_env_var = false
exclude_slash_tmp = false

See Sandbox & Approvals for details.

# Execute and exit with codex exec
codex exec "summarize all TODO comments in this project"

# Allow file edits
codex exec --full-auto "refactor this code"

# Full access (dangerous!)
codex exec --sandbox danger-full-access "your task"

# JSON output for automation
codex exec --json "analyze this project"

# Structured output with JSON schema
codex exec --output-schema schema.json "extract project details"

# Save output to file
codex exec -o output.txt "generate docs"

See Non-Interactive Mode (exec) for details.

# Pipe content to Codex
cat logs.txt | codex exec "find the error"

# Use in scripts
git diff | codex exec "create a commit message"

# Combine commands
codex exec "explain this file" < app.js > explanation.md

Warning: Skills are experimental and may change or be removed at any time before GA. Expect breaking changes and always check the official skills docs in the openai/codex repo for the latest status.

• What they are: Native, on-disk reusable capabilities that Codex can auto-discover. Each skill is a bundle with name, description, and an optional body kept on disk.
• Enable the feature flag:
  • Preferred: add to ~/.codex/config.toml

    [features]
    skills = true
    

  • One-off run: codex --enable skills
• Where skills live: ~/.codex/skills/**/SKILL.md (recursive). Only files named exactly SKILL.md count; hidden entries and symlinks are skipped.
• File format (YAML frontmatter + body):

  ---
  name: your-skill-name          # required, ≤ 100 chars, single line
  description: when/why to use   # required, ≤ 500 chars, single line
  ---
  
  # Optional body (kept on disk)
  Add references, workflows, or examples here.
  

• Using skills: Mention with $<skill-name> in chat or browse/insert via /skills in the TUI. Codex injects only name, description, and the absolute file path.
• Validation behavior: Invalid frontmatter triggers a dismissible startup modal and log entries; invalid skills are ignored until fixed.
• Sample skills in this repo: Copy or symlink any of the samples below into ~/.codex/skills/<name>/SKILL.md, then restart Codex with the feature flag enabled:
  • skills/pdf-processing/SKILL.md
  • skills/log-review/SKILL.md
  • skills/form-filling/SKILL.md
  • skills/project-management/SKILL.md
• Pair with GitHub Skills: You can combine Codex skills with the learning paths at github.com/skills to onboard teams quickly while keeping reusable Codex guidance locally.
• Community alternative (pre-native skills): The openskills project remains a viable open source option if you prefer a community-driven skills system.

The babysit-pr skill automates PR maintenance:

• Auto-fixes CI failures
• Handles review comments
• Watches for merge conflicts
• Keeps your PRs moving through the pipeline

# Use with MCP GitHub integration
codex "babysit this PR with $github"

Persistent JavaScript REPL for incremental code execution:

• Test code snippets in real-time
• Iterate on logic without full re-runs
• Debug complex expressions

# Enable in config.toml
[mcp_servers.js_repl]
command = "node"
args = ["-e", "process.stdin.on('data', d => eval(d.toString()))"]

New architecture for non-interactive exec mode:

• Faster startup times
• Better for CI/CD integration
• Reduced overhead for automation scripts

# Break down a large feature request
codex "Break down this feature request into actionable tasks:
- User authentication system
- Must support OAuth and email
- Include password reset flow
- Add 2FA option"

# Generate sprint backlog
codex exec "Analyze this project and create a sprint backlog:
- Prioritize by complexity
- Estimate effort in hours
- Identify dependencies"

# Create user stories
codex "Convert these requirements into user stories with acceptance criteria"

# Auto-generate PR descriptions
git diff | codex exec "Create a detailed PR description with:
- Summary of changes
- Testing performed
- Breaking changes (if any)"

# Create issues from TODO comments
codex exec "Scan for TODO/FIXME comments and create GitHub issues"

# Generate release notes
codex exec "Create release notes from recent commits"

# Generate status report
codex "Review recent commits and generate a status report for stakeholders"

# Track progress
codex "What percentage of sprint tasks are complete based on merged PRs?"

# Risk identification
codex "Analyze this project and identify potential blockers or risks"

# Code review automation
codex "Review this PR for:
- Security vulnerabilities
- Performance issues
- Code quality standards
- Test coverage gaps"

# Documentation sync
codex "Update the README based on recent feature additions"

# Onboarding assistance
codex "Create a new developer onboarding guide for this project"

You can create custom skills for your team's workflow:

# ~/.codex/skills/team-sprint/SKILL.md
---
name: team-sprint
description: Manage sprint planning and tracking for our team
---

# Sprint Workflow
1. Use `/standup` to generate daily standup summaries
2. Use `/retro` to collect retrospective feedback
3. Use `/velocity` to calculate team velocity

# Templates
- Sprint planning template in docs/sprint-template.md
- Retrospective format: Start/Stop/Continue

# Use codex-action for CI/CD
name: Code Review
on: [pull_request]
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: openai/codex-action@v1
        with:
          task: "Review this PR for security issues"

See GitHub Action for details.

# Review entire PR
codex "Review this PR for security, performance, and maintainability"

# Generate commit messages
git diff HEAD~1 | codex exec "Create a conventional commit message"

# Auto-fix common issues
codex "Fix all ESLint errors in this project"

# Generate CI config
codex "Create a GitHub Actions workflow for:
- TypeScript project
- Run tests on PR
- Deploy to Vercel on main"

# Debug CI failures
cat .github/workflows/build.log | codex exec "Find the root cause"

# Convert between languages
codex "Convert this Python utility to TypeScript"

# Update deprecated APIs
codex "Update all React class components to functional components with hooks"

# Add type safety
codex "Add TypeScript types to this JavaScript project"

# Analyze bottlenecks
codex "Profile this code and identify performance bottlenecks"

# Optimize database queries
codex "Refactor these N+1 queries to use batch loading"

# Bundle optimization
codex "Suggest webpack optimizations to reduce bundle size"

# Find vulnerabilities
codex "Audit this code for security vulnerabilities"

# Dependency checks
codex "Review package.json for outdated or vulnerable dependencies"

# Compliance check
codex "Check if this code follows OWASP security guidelines"

# Analyze error logs
cat error.log | codex exec "find the root cause"

# Debug specific function
codex "Debug why the login function is failing"

# Reproduce and fix
codex "Create a test case that reproduces this bug, then fix it"

# Generate README
codex exec "Create a comprehensive README for this project"

# API documentation
codex exec "Generate API docs from JSDoc comments"

# Code comments
codex "Add detailed comments to this complex function"

# Generate tests
codex "Create unit tests for all functions in utils.js"

# Test coverage
codex "Analyze test coverage and suggest missing tests"

# E2E test generation
codex "Create Playwright E2E tests for the user flow"

codex "Refactor this code to:
1. Improve readability
2. Add error handling
3. Follow TypeScript best practices
4. Add type definitions"