| name | codex |
| description | Execute Codex CLI for code analysis, refactoring, and automated code changes. Use when you need to delegate complex code tasks to Codex AI with file references (@syntax) and structured output. |
Codex CLI Integration
Overview
Execute Codex CLI commands and parse structured JSON responses. Supports file references via @ syntax, multiple models, and sandbox controls.
When to Use
- Complex code analysis requiring deep understanding
- Large-scale refactoring across multiple files
- Automated code generation with safety controls
- Tasks requiring specialized reasoning models (o3, gpt-5)
Usage
bash scripts/codex.sh "<task>" [model] [working_dir]
Timeout: Set timeout: 7200000 (2 hours) in Bash tool for long tasks.
Parameters
task(required): Task description, supports@filereferencesmodel(optional): Model to use (default: gpt-5-codex)gpt-5-codex: Default, optimized for codegpt-5: Fast general purposeo3: Deep reasoningo4-mini: Quick taskscodex-1: Software engineering
working_dir(optional): Working directory (default: current)
Return Format
Extracts agent_message from Codex JSON stream:
Agent response text here...
Error format:
ERROR: Error message
Examples
Basic code analysis:
bash scripts/codex.sh "explain @src/main.ts"
Refactoring with specific model:
bash scripts/codex.sh "refactor @src/utils for performance" "gpt-5"
Multi-file analysis:
bash scripts/codex.sh "analyze @. and find security issues" "gpt-5-codex" "/path/to/project"
Quick task:
bash scripts/codex.sh "add comments to @utils.js" "gpt-5-codex"
Notes
- Runs with
--dangerously-bypass-approvals-and-sandboxfor automation - Uses
--skip-git-repo-checkto work in any directory - Streams progress, returns only final agent message
- Requires Codex CLI installed and authenticated
- Use
timeout: 7200000(2 hours) for complex tasks that may take longer