codex-cli

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.

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"

1. Safety Mode Selection

Choose the appropriate safety mode based on task requirements:

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

```bash

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

```

Full Automation - When file modifications are needed:

```bash

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

```

Unrestricted Mode - Only when network access is required:

```bash

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)

```bash

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

```

Activity logs to stderr, final output to stdout.

Save to File

```bash

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

```

JSON Streaming for Monitoring

```bash

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

```

Captures events: turn.started, command_execution, file_change, etc.

Structured Schema Output

```bash

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

```

Enforces specific JSON structure for automation pipelines.

3. Session-Based Workflows

Maintain context across multiple related tasks:

```bash

# 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"

```

Note: Behavior flags must be re-specified on resume (e.g., --full-auto).

4. Automation Integration

Integrate Codex into CI/CD or development workflows:

```bash

# 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")'

```

Code Analysis Task

```bash

# 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

```bash

# 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

```bash

# 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

```bash

# 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"

```

Git Repository Requirement

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

```bash

codex exec --skip-git-repo-check ""

```

Authentication

Use default Codex CLI credentials or override:

```bash

CODEX_API_KEY=your-key-here codex exec ""

```

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.

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:

```bash

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

```

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