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

| Command | Purpose | |---------|---------| | /help | Show available commands | | /clear | Clear conversation | | /status | Show session info | | /compact | Compress context | | /model | Change model | | /bug | Report a bug |

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Ctrl+C | Cancel operation | | Ctrl+D | Exit CLI | | Ctrl+L | Clear screen | | Enter | Send message | | Shift+Enter | New line |

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

| Resource | When to Consult | |----------|-----------------| | readme.md | Overview, installation, quickstart | | getting-started.md | CLI usage, tips, example prompts | | install.md | Installation options | | authentication.md | Auth methods, API keys, headless login |

Configuration

| Resource | When to Consult | |----------|-----------------| | config.md | Full configuration reference | | example-config.md | Example configurations | | agents-md.md | Root AGENTS.md file | | agents-md-guide.md | Writing effective AGENTS.md |

Security & Sandboxing

| Resource | When to Consult | |----------|-----------------| | sandbox.md | Sandbox mode, permissions | | execpolicy.md | Command execution policies | | platform-sandboxing.md | Platform-specific sandboxing | | windows-sandbox.md | Windows sandbox security | | zero-data-retention.md | ZDR mode |

Features

| Resource | When to Consult | |----------|-----------------| | exec.md | Non-interactive mode | | prompts.md | Custom prompts | | skills.md | Codex skills | | slash-commands.md | Slash commands | | advanced.md | MCP, tracing, advanced features |

Reference

| Resource | When to Consult | |----------|-----------------| | faq.md | Frequently asked questions | | changelog.md | Version history | | contributing.md | Contributing guidelines | | sdk/typescript.md | TypeScript SDK |

Syncing Documentation

Resources are synced from the official OpenAI Codex GitHub repository:

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