OpenAI Codex CLI Development

Source: https://github.com/openai/codex

Codex CLI is OpenAI's AI-powered coding agent that runs locally. This skill provides quick reference for effective usage, configuration, and integration.

Best Practices

Getting Started

• Install via npm: npm install -g @openai/codex or brew install --cask codex
• Authenticate with ChatGPT - Sign in with your ChatGPT Plus/Pro/Team account
• Create an AGENTS.md in project roots with project-specific context
• Use trusted directories to grant file system access

Effective Usage

• Be specific with requests - "Refactor Dashboard to React Hooks" beats "fix code"
• Use resume for long tasks - codex resume --last continues previous sessions
• Leverage non-interactive mode - codex exec "..." for automation

Model Selection

Codex uses GPT-4o by default. Override with --model:

codex --model gpt-4o          # Default, balanced
codex --model gpt-4o-mini     # Faster, cheaper
codex --model o1-preview      # Advanced reasoning

Configuration

Configuration lives in ~/.codex/config.toml:

[model]
name = "gpt-4o"

[sandbox]
enabled = true
permissions = ["read", "write", "execute"]

[mcp_servers]
my-server = { command = "node", args = ["./server.js"] }

AGENTS.md Files

Create project context files:

<!-- AGENTS.md -->
# Project Context

This is a React TypeScript project using:
- Vite for bundling
- Tailwind CSS for styling
- React Query for data fetching

## Conventions
- Use functional components with hooks
- Place components in src/components/
- Run `npm test` before committing

Sandbox & Security

• Sandbox mode restricts file system and network access
• Execpolicy defines rules for allowed commands
• Approval modes: suggest (default), auto-edit, full-auto

# Run with auto-approval for safe commands
codex --approval-mode auto-edit

# Strict sandbox mode
codex --sandbox

Non-Interactive Mode

Use codex exec for automation and CI/CD:

# Single command
codex exec "fix lint errors in src/"

# With specific model
codex exec -m gpt-4o-mini "add TypeScript types to utils/"

# JSON output for scripting
codex exec --json "list all TODO comments"

Quick Reference

Common Commands

# Interactive session
codex

# With initial prompt
codex "explain this codebase"

# Non-interactive
codex exec "fix the bug in auth.ts"

# Resume previous session
codex resume --last
codex resume <SESSION_ID>

# Show status
codex status

Slash Commands

Keyboard Shortcuts

Environment Variables

OPENAI_API_KEY         # API key (if using API billing)
CODEX_MODEL            # Default model
CODEX_SANDBOX          # Enable sandbox (true/false)
CODEX_HOME             # Config directory (~/.codex)

Documentation Index

Detailed documentation synced from the official GitHub repository.

Getting Started

Configuration

Security & Sandboxing

Features

Reference

Syncing Documentation

Resources are synced from the official OpenAI Codex GitHub repository:

cd skills/openai-codex
bun run scripts/sync-docs.ts