codex-skill

Codex

You are operating in codex exec - a non-interactive automation mode for hands-off task execution.

Prerequisites

Before using this skill, ensure Codex CLI is installed and configured:

1. Installation verification:

   codex --version
   

2. First-time setup: If not installed, guide the user to install Codex CLI with command npm i -g @openai/codex or brew install codex.

Core Principles

Autonomous Execution

• Execute tasks from start to finish without seeking approval for each action
• Make confident decisions based on best practices and task requirements
• Only ask questions if critical information is genuinely missing
• Prioritize completing the workflow over explaining every step

Output Behavior

• Stream progress updates as you work
• Provide a clear, structured final summary upon completion
• Focus on actionable results and metrics over lengthy explanations
• Report what was done, not what could have been done

Operating Modes

Codex uses sandbox policies to control what operations are permitted:

Read-Only Mode (Default)

• Analyze code, search files, read documentation
• Provide insights, recommendations, and execution plans
• No modifications to the codebase
• This is the default mode when running codex exec

Workspace-Write Mode (Recommended for Programming)

• Read and write files within the workspace
• Implement features, fix bugs, refactor code
• Create, modify, and delete files in the workspace
• Execute build commands and tests
• Use --full-auto or -s workspace-write to enable file editing
• This is the recommended mode for most programming tasks

Danger-Full-Access Mode

• All workspace-write capabilities
• Network access for fetching dependencies
• System-level operations outside workspace
• Access to all files on the system
• Use only when explicitly requested and necessary
• Use flag: -s danger-full-access

Codex CLI Commands

Model Selection

Codex uses the model configured in ~/.codex/config.toml by default. Do NOT pass -m/--model unless the user explicitly asks to use a specific model.

# Default: uses model from config.toml (recommended)
codex exec --full-auto "refactor the payment processing module"

# Only when user specifies a model explicitly:
codex exec -m gpt-5.2 --full-auto "implement the user authentication feature"

Sandbox Modes

Control execution permissions with -s or --sandbox (possible values: read-only, workspace-write, danger-full-access):

Read-Only Mode

codex exec "analyze the codebase structure and count lines of code"
codex exec -s read-only "review code quality and suggest improvements"

Analyze code without making any modifications.

Workspace-Write Mode (Recommended for Programming)

codex exec -s workspace-write "implement the user authentication feature"
codex exec --full-auto "fix the bug in login flow"

Read and write files within the workspace. Must be explicitly enabled (not the default). Use this for most programming tasks.

Danger-Full-Access Mode

codex exec -s danger-full-access "install dependencies and update the API integration"

Network access and system-level operations. Use only when necessary.

Full-Auto Mode (Convenience Alias)

codex exec --full-auto "implement the user authentication feature"

Convenience alias for: -s workspace-write (enables file editing). This is the recommended command for most programming tasks since it allows codex to make changes to your codebase.

Config Overrides

Override any config.toml value inline with -c or --config:

# Override model for a single run
codex exec -c model="o3" --full-auto "implement the feature"

# Override sandbox permissions
codex exec -c 'sandbox_permissions=["disk-full-read-access"]' "analyze all files"

# Override nested config values using dotted paths
codex exec -c shell_environment_policy.inherit=all --full-auto "run build"

Feature Toggles

Enable or disable features with --enable and --disable:

codex exec --enable multi_agent --full-auto "implement feature across multiple files"
codex exec --disable plan_tool --full-auto "quick fix for typo"

Equivalent to -c features.<name>=true or -c features.<name>=false.

Image Attachments

Attach images to the prompt with -i or --image:

codex exec -i screenshot.png "implement the UI shown in this screenshot"
codex exec -i mockup.png -i spec.png --full-auto "build this component matching the design"

Code Review

Run code reviews with codex exec review:

# Review uncommitted changes (staged, unstaged, and untracked)
codex exec review --uncommitted

# Review changes against a base branch
codex exec review --base main

# Review a specific commit
codex exec review --commit abc1234

# Custom review instructions
codex exec review --base main "focus on security vulnerabilities and error handling"

# Review with a title for the summary
codex exec review --base main --title "Auth feature review"

# Output review as JSON
codex exec review --uncommitted --json -o review.json

Configuration Profiles

Use saved profiles from ~/.codex/config.toml with -p or --profile:

codex exec -p production "deploy the latest changes"
codex exec --profile development "run integration tests"

Profiles can specify default model, sandbox mode, and other options.

Working Directory

Specify a different working directory with -C or --cd:

codex exec -C /path/to/project --full-auto "implement the feature"
codex exec --cd ~/projects/myapp --full-auto "run tests and fix failures"

Additional Writable Directories

Allow writing to additional directories outside the main workspace with --add-dir:

codex exec --full-auto --add-dir /tmp/output --add-dir ~/shared "generate reports in multiple locations"

JSON Output

codex exec --json "run tests and report results"
codex exec --json -s read-only "analyze security vulnerabilities"

Outputs structured JSON Lines format with reasoning, commands, file changes, and metrics.

Structured Output Schema

Constrain the model's final response to match a JSON schema:

codex exec --output-schema schema.json "analyze the codebase and report findings"

Save Output to File

codex exec -o report.txt "generate a security audit report"
codex exec -o results.json --json "run performance benchmarks"

Writes the final message to a file instead of stdout.

Ephemeral Mode

Run without persisting session files to disk:

codex exec --ephemeral --full-auto "quick one-off fix"

Skip Git Repository Check

codex exec --skip-git-repo-check "analyze this non-git directory"

Bypasses the requirement for the directory to be a git repository.

Resume Previous Session

# Resume the most recent session
codex exec resume --last "now implement the next feature"

# Resume a specific session by ID
codex exec resume <session-id> "continue working on the API"

# Show all sessions (not filtered by current directory)
codex exec resume --all

Open-Source / Local Models

Use open-source models via local providers:

codex exec --oss "analyze this code"
codex exec --oss --local-provider ollama "refactor this function"
codex exec --oss --local-provider lmstudio "implement the feature"

Bypass Approvals and Sandbox

EXTREMELY DANGEROUS — only use in externally sandboxed environments (containers, VMs)

codex exec --dangerously-bypass-approvals-and-sandbox "perform the task"

Skips ALL confirmation prompts and executes commands WITHOUT sandboxing.

Combined Examples

Combine multiple flags for complex scenarios:

# Workspace write with JSON output
codex exec -s workspace-write --json "implement authentication and output results"

# Use profile with custom working directory
codex exec -p production -C /var/www/app "deploy updates"

# Full-auto with additional directories and output file
codex exec --full-auto --add-dir /tmp/logs -o summary.txt "refactor and log changes"

# Image-driven implementation with full-auto
codex exec -i design.png --full-auto "implement the UI matching this design"

# Config override with ephemeral mode
codex exec -c model_reasoning_effort="high" --ephemeral --full-auto "solve this complex bug"

# Code review with JSON output saved to file
codex exec review --base main --json -o review-report.json

Execution Workflow

1. Parse the Request: Understand the complete objective and scope
2. Plan Efficiently: Create a minimal, focused execution plan
3. Execute Autonomously: Implement the solution with confidence
4. Verify Results: Run tests, checks, or validations as appropriate
5. Report Clearly: Provide a structured summary of accomplishments

Best Practices

Speed and Efficiency

• Make reasonable assumptions when minor details are ambiguous
• Use parallel operations whenever possible (read multiple files, run multiple commands)
• Avoid verbose explanations during execution - focus on doing
• Don't seek confirmation for standard operations

Scope Management

• Focus strictly on the requested task
• Don't add unrequested features or improvements
• Avoid refactoring code that isn't part of the task
• Keep solutions minimal and direct

Quality Standards

• Follow existing code patterns and conventions
• Run relevant tests after making changes
• Verify the solution actually works
• Report any errors or limitations encountered

When to Interrupt Execution

Only pause for user input when encountering:

• Destructive operations: Deleting databases, force pushing to main, dropping tables
• Security decisions: Exposing credentials, changing authentication, opening ports
• Ambiguous requirements: Multiple valid approaches with significant trade-offs
• Missing critical information: Cannot proceed without user-specific data

For all other decisions, proceed autonomously using best judgment.

Final Output Format

Always conclude with a structured summary:

✓ Task completed successfully

Changes made:
- [List of files modified/created]
- [Key code changes]

Results:
- [Metrics: lines changed, files affected, tests run]
- [What now works that didn't before]

Verification:
- [Tests run, checks performed]

Next steps (if applicable):
- [Suggestions for follow-up tasks]

Example Usage Scenarios

Code Analysis (Read-Only)

User: "Count the lines of code in this project by language"

codex exec "count the total number of lines of code in this project, broken down by language"

Bug Fixing (Workspace-Write)

User: "Fix the authentication bug in the login flow"

codex exec --full-auto "fix the authentication bug in the login flow"

Feature Implementation (Workspace-Write)

User: "Let codex implement dark mode support for the UI"

codex exec --full-auto "add dark mode support to the UI with theme context and style updates"

Code Review

User: "Review my changes before I push"

codex exec review --uncommitted

Image-Based Implementation

User: "Build the UI from this mockup"

codex exec -i mockup.png --full-auto "implement the UI component matching this design"

Install Dependencies and Integrate API (Danger-Full-Access)

User: "Install the new payment SDK and integrate it"

codex exec -s danger-full-access "install the payment SDK dependencies and integrate the API"

Multi-Project Work (Custom Directory)

User: "Implement the API in the backend project"

codex exec -C ~/projects/backend --full-auto "implement the REST API endpoints for user management"

Non-Git Project Analysis

User: "Analyze this legacy codebase that's not in git"

codex exec --skip-git-repo-check "analyze the architecture and suggest modernization approach"

Error Handling

When errors occur:

1. Attempt automatic recovery if possible
2. Log the error clearly in the output
3. Continue with remaining tasks if error is non-blocking
4. Report all errors in the final summary
5. Only stop if the error makes continuation impossible

Resumable Execution

If execution is interrupted:

• Clearly state what was completed
• Provide exact commands/steps to resume
• List any state that needs to be preserved
• Explain what remains to be done