export default codex

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

Recommended approach (use uv run to manage the Python environment automatically):

uv run ~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]

Alternative approach (run directly or via Python):

~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]
# Or
python3 ~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]

Resume session:

uv run ~/.claude/skills/codex/scripts/codex.py resume <session_id> "<task>" [model] [working_dir]

Timeout Control

• Built-in: Script enforces 2-hour timeout by default
• Override: Set CODEX_TIMEOUT environment variable (in milliseconds, e.g., CODEX_TIMEOUT=3600000 for 1 hour)
• Behavior: On timeout, sends SIGTERM, then SIGKILL after 5s if process doesn't exit
• Exit code: Returns 124 on timeout (consistent with GNU timeout)
• Bash tool: Always set timeout: 7200000 parameter for double protection

Parameters

• task (required): Task description, supports @file references
  • Important: When task length exceeds 800 characters, the script automatically switches to stdin mode to avoid shell escaping issues
  • You will see a warning in stderr: WARN: Task length (XXX chars) exceeds threshold, using stdin mode...
  • This behavior is transparent and handled automatically - no manual intervention needed
• model (optional): Model to use (default: gpt-5.1-codex)
  • gpt-5.1-codex: Default, optimized for code
  • gpt-5: Fast general purpose
• working_dir (optional): Working directory (default: current)

Return Format

Extracts agent_message from Codex JSON stream and appends session ID:

Agent response text here...

---
SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14

Error format (stderr):

ERROR: Error message

Invocation Pattern

When calling via Bash tool, always include the timeout parameter:

Bash tool parameters:
- command: uv run ~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]
- timeout: 7200000
- description: <brief description of the task>

Alternatives:

# Direct execution (simplest)
- command: ~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]

# Using python3
- command: python3 ~/.claude/skills/codex/scripts/codex.py "<task>" [model] [working_dir]

Examples

Basic code analysis:

# Recommended: via uv run (auto-manages Python environment)
uv run ~/.claude/skills/codex/scripts/codex.py "explain @src/main.ts"
# timeout: 7200000

# Alternative: direct execution
~/.claude/skills/codex/scripts/codex.py "explain @src/main.ts"

Refactoring with specific model:

uv run ~/.claude/skills/codex/scripts/codex.py "refactor @src/utils for performance" "gpt-5"
# timeout: 7200000

Multi-file analysis:

uv run ~/.claude/skills/codex/scripts/codex.py "analyze @. and find security issues" "gpt-5-codex" "/path/to/project"
# timeout: 7200000

Resume previous session:

# First session
uv run ~/.claude/skills/codex/scripts/codex.py "add comments to @utils.js" "gpt-5-codex"
# Output includes: SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14

# Continue the conversation
uv run ~/.claude/skills/codex/scripts/codex.py resume 019a7247-ac9d-71f3-89e2-a823dbd8fd14 "now add type hints"
# timeout: 7200000

Using python3 directly (alternative):

python3 ~/.claude/skills/codex/scripts/codex.py "your task here"

Notes

• Recommended: Use uv run for automatic Python environment management (requires uv installed)
• Alternative: Direct execution ./codex.py (uses system Python via shebang)
• Python implementation using standard library (zero dependencies)
• Cross-platform compatible (Windows/macOS/Linux)
• PEP 723 compliant (inline script metadata)
• Runs with --dangerously-bypass-approvals-and-sandbox for automation (new sessions only)
• Uses --skip-git-repo-check to work in any directory
• Streams progress, returns only final agent message
• Every execution returns a session ID for resuming conversations
• Requires Codex CLI installed and authenticated

Automatic stdin Mode (800+ Character Threshold)

The wrapper automatically handles long task inputs to avoid shell argument length limits and escaping issues:

• Threshold: 800 characters (configurable via STDIN_THRESHOLD in codex.py)
• Behavior: When task exceeds threshold, codex.py:
  1. Writes warning to stderr: WARN: Task length (XXX chars) exceeds threshold, using stdin mode...
  2. Passes - to codex CLI (signals stdin input)
  3. Writes task content to process stdin
  4. Closes stdin pipe
• Transparent: No change in command syntax required - just pass long strings normally
• Applies to: Both new sessions and resume mode
• Why: Prevents issues with shell quoting, special characters, and argument length limits across different shells (bash/zsh/PowerShell)