Codex CLI Configuration

OpenAI Codex CLI setup with skills, workflows, and profiles ported from Claude Code.

Quick Start

# Use a profile
codex --profile ultrathink "review this architecture"
codex --profile execute "implement next task"
codex --profile ship "complete feature workflow"

# Use skills (explicit invocation)
codex "Use ship skill"
codex "Use execute skill"
codex "Use ultrathink skill"

Repository Layout

• config/ – Canonical CLI configuration (config.toml, config.json) plus MCP blocks
• skills/ – Skill library (skills/<name>/SKILL.md)
• rules/ – Command allow/deny rules
• scripts/ – Operational tooling (doctor, lint-config, check-skills, check-mcp-exa)
• secrets/ – Non-committed env stubs (copy exa.env.example → exa.env, export before use)
• docs/CHANGELOG.md – Versioned history for repo changes
• agents/ – Persona instructions for reviews

Profiles

Configured in config/config.toml, profiles switch between different model and approval settings.

ultrathink - Deep Architectural Review

• Model: GPT-5
• Reasoning: High
• Approval: Never
• Use for: Design critique, complexity analysis, architecture decisions

execute - Tactical Implementation

• Model: GPT-5-Codex
• Reasoning: Medium
• Approval: Never
• Use for: Task execution, feature implementation, coding work

ship - Complete Workflows

• Model: GPT-5-Codex
• Reasoning: High
• Approval: Never
• Use for: End-to-end feature delivery, spec → implementation → PR

fast - Quick Tasks

• Model: GPT-5
• Reasoning: Low
• Approval: Never
• Use for: Quick edits, simple refactors, minor fixes

Skills

Skills replace prompts. Each skill lives in skills/<name>/SKILL.md with frontmatter metadata.

Invocation:

• Explicit: mention the skill name, e.g., “Use ship skill”
• Implicit: describe the task; the agent will pick matching skills

Example Workflows

Complete Feature Development

# High-reasoning full workflow
codex --profile ship "Use ship skill"

# Or step-by-step:
codex "Use prime skill"       # Recon project state and conventions
codex "Use spec skill"        # Produce the PRD with alternatives
codex "Use plan skill"        # Build issue task list
codex "Use flesh skill"       # Clarify vague tasks
codex "Use execute skill"     # Implement the next task
codex "Use debug skill"       # Optional: bug hunts
codex "Use qa-cycle skill"    # Test and fix
codex "Use pr skill"          # Draft PR title + body
codex "Use code-review skill" # Brutal self-review
codex "Use pr-ready skill"    # Final quality gate

Design Review

codex --profile ultrathink "Use ultrathink skill"

Task Execution

codex --profile execute "Use execute skill"

Code Review

codex "Use ousterhout skill"
codex "Use testing skill"

Shell Aliases

Add to your ~/.zshrc or ~/.bashrc:

# Codex with profiles
alias cdx='codex'
alias cdx-think='codex --profile ultrathink'
alias cdx-exec='codex --profile execute'
alias cdx-ship='codex --profile ship'
alias cdx-fast='codex --profile fast'

# Common skills
alias cdx-ultra='codex "Use ultrathink skill"'
alias cdx-arch='codex "Use architect skill"'
alias cdx-prime='codex "Use prime skill"'
alias cdx-spec='codex "Use spec skill"'
alias cdx-plan='codex "Use plan skill"'
alias cdx-do='codex "Use execute skill"'
alias cdx-qa='codex "Use qa-cycle skill"'
alias cdx-ready='codex "Use pr-ready skill"'
alias cdx-debug='codex "Use debug skill"'
alias cdx-pr='codex "Use pr skill"'
alias cdx-review='codex "Use code-review skill"'
alias cdx-respond='codex "Use git-respond skill"'
alias cdx-ci='codex "Use ci skill"'

Then reload: source ~/.zshrc

EXA MCP Integration

1. Copy secrets/exa.env.example → secrets/exa.env, populate EXA_API_KEY.
2. Export the variable (source secrets/exa.env or add to your shell profile).
3. Run scripts/check-mcp-exa.sh to confirm connectivity.
4. Codex consumes the key via the [mcp.exa] block in config/config.toml or config/config.json.

Operational Scripts

scripts/doctor.sh          # One-stop health check (git, config, skills, MCP)
scripts/lint-config.sh     # Validates JSON/TOML
scripts/check-skills.sh    # Ensures SKILL frontmatter exists
scripts/check-mcp-exa.sh   # Lightweight EXA MCP ping (requires EXA_API_KEY)

Integrate scripts/doctor.sh into your pre-flight routine before large edits.

Configuration Files

• config/config.toml - Main configuration with profiles, project trust levels, and MCP settings
• config/config.json - Provider registry mirrored for Codex
• AGENTS.md - Core philosophy and design principles
• skills/ - Skill library organized by name
• rules/ - Command allow/deny rules

Philosophy

This configuration mirrors the Claude Code workflow system, bringing:

1. Complexity Management - Ousterhout principles baked into every workflow
2. Quality Gates - Automated validation before PR creation
3. Workflow Orchestration - Guided processes from spec to shipped feature
4. Profile-Based Context - Switch between deep thinking and fast execution

Customization

Adding New Skills

Create skills/<name>/SKILL.md:

---
name: my-skill
description: What this skill does
aliases: [short-name]
enabled: true
---

# My Skill

Prompt content here...

Invoke with: codex "Use my-skill skill"

Adding New Profiles

Edit config/config.toml:

[profiles.myprofile]
model = "gpt-5-codex"
model_reasoning_effort = "medium"
approval_policy = "never"
sandbox_mode = "workspace-write"