codex-exec

name	codex-exec
description	Execute OpenAI Codex CLI prompts in non-interactive mode and return structured results. Enables hybrid AI workflows combining your AI agent's reasoning with Codex code generation. Supports text and JSON output, effort levels (minimal to xhigh), model override, timeout control, and full-auto mode. Use for code generation, research, analysis, and reasoning tasks via openai codex CLI.

Codex Exec Skill

Execute OpenAI Codex CLI prompts in non-interactive mode and return structured results. Enables hybrid workflows combining any AI coding agent with Codex's code generation and reasoning capabilities.

Prerequisites

• Node.js 18+ required
• Codex CLI installed: npm install -g @openai/codex
• Authentication: Set OPENAI_API_KEY environment variable, or run codex once to log in interactively

Installation

Install this skill via skills.sh:

npx skills add baekenough/baekenough-skills --skill codex-exec

Compatibility: Works with Claude Code, Cursor, Windsurf, and any AI coding agent that supports the skills.sh standard.

Options

--prompt <text>   Required. The prompt to send to Codex CLI
--json            Return structured JSON Lines output
--output <path>   Save final message to file
--model <name>    Model override (o3, o4-mini, etc.)
--timeout <ms>    Execution timeout (default: 120000, max: 600000)
--full-auto       Enable auto-approval mode (codex -a full-auto)
--working-dir     Working directory for Codex execution
--effort <level>  Set reasoning effort level (minimal, low, medium, high, xhigh)
                  Maps to Codex CLI's model_reasoning_effort config
                  Default: uses Codex CLI's configured default
                  Recommended: xhigh for research and analysis tasks

Workflow

1. Pre-checks
   - Verify `codex` binary is installed (which codex || npx codex --version)
   - Verify authentication (OPENAI_API_KEY set or codex logged in)
2. Build command
   - Base: codex exec --ephemeral "<prompt>"
   - Apply options: --json, --model, --full-auto, -C <dir>
   - Set --working-dir if specified
3. Execute
   - Run via Bash tool with timeout (default 2min, max 10min)
   - Or use helper script: node scripts/codex-wrapper.cjs
4. Parse output
   - Text mode: return raw stdout
   - JSON mode: parse JSON Lines, extract final assistant message
5. Report results
   - Format output with execution metadata

Safety Defaults

• --ephemeral: No session persistence (conversations not saved)
• Default mode: Normal approval (Codex prompts for confirmation on file changes)
• Override with --full-auto only when the task and environment are trusted

Output Format

Success (Text Mode)

[Codex Exec] Completed

Model: o3
Duration: 23.4s
Working Dir: /path/to/project

--- Output ---
{codex response text}

Success (JSON Mode)

[Codex Exec] Completed (JSON)

Model: o3
Duration: 23.4s
Events: 12

--- Final Message ---
{extracted final assistant message}

Failure

[Codex Exec] Failed

Error: {error_message}
Exit Code: {code}
Suggested Fix: {suggestion}

Helper Script

For complex executions, use the wrapper script:

node scripts/codex-wrapper.cjs --prompt "your prompt" [options]

The wrapper provides:

• Environment validation (binary + auth checks)
• Safe command construction
• JSON Lines parsing with event extraction
• Structured JSON output
• Timeout handling with graceful termination

Examples

# Simple text prompt
node scripts/codex-wrapper.cjs --prompt "explain what this project does"

# JSON output with model override
node scripts/codex-wrapper.cjs --prompt "list all TODO items" --json --model o4-mini

# Save output to file
node scripts/codex-wrapper.cjs --prompt "generate a README" --output ./README.md

# Full auto mode with custom timeout
node scripts/codex-wrapper.cjs --prompt "fix the failing tests" --full-auto --timeout 300000

# Specify working directory
node scripts/codex-wrapper.cjs --prompt "analyze the codebase" --working-dir /path/to/project

# Research task with maximum reasoning depth
node scripts/codex-wrapper.cjs --prompt "Research and analyze: {topic}" --effort xhigh --full-auto --json

Availability Check

This skill requires the Codex CLI binary to be installed and authenticated. It is only usable when:

1. codex binary is found in PATH (which codex succeeds)
2. Authentication is valid (OPENAI_API_KEY is set, or codex is logged in interactively)

If either check fails, the skill cannot execute. Fall back to your agent's native web search or reasoning tools for the task.

Effort Level Guide

Level	Use Case	Speed	Depth
minimal	Quick lookups	Fastest	Surface
low	Simple queries	Fast	Basic
medium	General tasks	Balanced	Standard
high	Complex analysis	Slower	Deep
xhigh	Research and investigation	Slowest	Maximum