codex-cli

name	codex-cli
description	Use OpenAI Codex CLI in non-interactive mode for automated code analysis, review, and programmatic task execution. Trigger on requests like "use Codex to analyze", "run codex exec", "codex code review", or when users want AI-powered code analysis without interactive prompts. Ideal for automation workflows, code quality checks, and generating structured analysis reports.

Codex CLI Non-Interactive Mode

Overview

Execute OpenAI's Codex CLI in non-interactive mode (codex exec) to automate code analysis, reviews, and other development tasks without requiring user approvals. The tool operates with configurable safety modes and supports structured outputs for integration into automation pipelines.

When to Use This Skill

Use Codex CLI when the user requests:

• Code analysis or architectural reviews using AI assistance
• Automated code quality checks or security audits
• Generating reports (changelogs, documentation, etc.) from code
• Multi-step analysis workflows that benefit from persistent context
• Integration with automation pipelines requiring structured output

Trigger phrases: "use Codex to...", "run codex exec", "codex analyze", "have codex review"

Core Capabilities

1. Safety Mode Selection

Choose the appropriate safety mode based on task requirements:

Read-Only (Default) - For analysis and review tasks:

codex exec "Analyze the authentication flow and identify potential security issues"

Full Automation - When file modifications are needed:

codex exec --full-auto "Refactor the user service to follow SOLID principles"

Unrestricted Mode - Only when network access is required:

codex exec --sandbox danger-full-access "Test API endpoints and validate responses"

Decision Guidelines:

• Start with read-only for initial exploration
• Use --full-auto when the user explicitly requests code changes
• Reserve unrestricted mode for tasks requiring network operations
• Always inform the user which mode is being used and why

2. Output Handling

Configure output format based on downstream requirements:

Default (Pipe-Friendly)

codex exec "Generate changelog from last 10 commits" > changelog.md

Activity logs to stderr, final output to stdout.

Save to File

codex exec "Review code for type errors" -o review-report.txt

JSON Streaming (JSONL to stdout)

codex exec --json "Comprehensive security audit" 2>&1 | tee audit-log.jsonl

With --json, stdout becomes a JSONL stream of every event (stderr retains progress output). Events include thread.started, turn.started, turn.completed, item.started, item.completed, and error. Item types: agent_message, command_execution, file_change, reasoning, mcp_tool_call, web_search, plan_update.

Filter specific events:

# Extract only agent messages
codex exec --json "<task>" | jq 'select(.type == "item.completed" and .item.type == "agent_message")'

# Track token usage per turn
codex exec --json "<task>" | jq 'select(.type == "turn.completed") | .usage'

Structured Schema Output

codex exec "Find all TODO comments with context" --output-schema todo-schema.json

Enforces specific JSON structure for automation pipelines.

3. Session-Based Workflows

Sessions are persisted to disk by default, enabling resume across invocations and environments.

# Initial analysis
codex exec "Analyze the codebase architecture"
# Returns session ID, e.g., session_abc123

# Follow-up with context
codex exec resume --last "Now identify performance bottlenecks in the identified critical paths"

# Or resume specific session
codex exec resume session_abc123 "Generate refactoring recommendations"

Taking over a non-interactive session: Resume a session started elsewhere (e.g., CI pipeline) from your local machine:

# In CI: run analysis, capture session ID from output
SESSION_ID=$(codex exec --json "Audit dependencies for vulnerabilities" 2>/dev/null | jq -r 'select(.type=="thread.started") | .session_id')

# Locally: take over with full context preserved
codex exec resume "$SESSION_ID" "Fix the critical vulnerabilities you found" --full-auto

Ephemeral sessions — use --ephemeral to skip persisting session data to disk (useful for one-shot CI tasks that won't be resumed):

codex exec --ephemeral "Generate test coverage report" -o coverage.md

Notes:

• Behavior flags (--full-auto, --sandbox, etc.) must be re-specified on resume
• Session data is stored locally; cross-machine resume requires shared storage or transferring session files

4. Automation Integration

Integrate Codex into CI/CD or development workflows:

# Code review in PR pipeline
codex exec --json "Review uncommitted changes for bugs and style issues" \
  --output-schema review-schema.json > review.json

# Generate documentation
codex exec "Generate API documentation from comments" -o api-docs.md

# Security scanning
codex exec "Scan for OWASP Top 10 vulnerabilities" --json 2>&1 | \
  jq 'select(.type=="item.completed" and .item.type=="agent_message")'

Task Execution Patterns

Code Analysis Task

# User asks: "Use Codex to analyze our error handling patterns"
codex exec "Analyze error handling patterns across the codebase. Identify inconsistencies, anti-patterns, and suggest improvements."

Code Review Task

# User asks: "Have Codex review the recent changes"
codex exec --full-auto "Review git diff for the last commit. Check for bugs, security issues, and code quality problems."

Report Generation Task

# User asks: "Generate a changelog using Codex"
codex exec "Generate a changelog from commits since last release tag. Group by feature, bugfix, and breaking changes." -o CHANGELOG.md

Multi-Step Investigation

# User asks: "Use Codex to investigate the performance issues"
codex exec "Profile the application and identify performance bottlenecks"
# Review results, then:
codex exec resume --last "Deep dive into the database query performance issues you identified"

Important Considerations

Git Repository Requirement

Codex requires a Git repository to track changes safely. Override only when necessary:

codex exec --skip-git-repo-check "<task>"

Authentication

Use default Codex CLI credentials or override:

CODEX_API_KEY=your-key-here codex exec "<task>"

Error Handling

• Check exit codes: $? for success/failure
• Stderr contains activity logs and errors
• JSON mode provides structured error events

Model Selection

Codex CLI defaults to appropriate models based on platform. Explicit model selection happens in interactive mode only.

Reference Documentation

For detailed command syntax, all available flags, and advanced use cases, consult:

• references/codex-exec-reference.md - Comprehensive command reference

Use rg to search reference documentation when specific flag information is needed:

rg "resume" references/codex-exec-reference.md

Best Practices

1. Always explain the chosen safety mode to the user
2. Start conservative (read-only) and escalate permissions only when needed
3. Capture session IDs when planning multi-step workflows
4. Use structured outputs (--output-schema) for automation reliability
5. Monitor JSON streams for long-running tasks to provide progress updates
6. Combine with shell tools (jq, grep, etc.) for post-processing
7. Preserve context through session resume for complex investigations