codex

NAME

codex - execute non-interactive OpenAI Codex prompts

SYNOPSIS

state-name:
  tool: codex
  arguments:
    prompt: <prompt-text>
    model: <model-name>   # optional
    timeout: <duration>   # optional

DESCRIPTION

The codex tool invokes OpenAI’s Codex CLI (codex exec) for code-focused AI tasks. It sends a prompt and captures the response, suitable for code generation, analysis, and transformation tasks.

The tool runs in the project root directory for full codebase context.

ARGUMENTS

Argument	Required	Default	Description
`prompt`	Yes	-	The prompt to send to Codex
`model`	No	Default model	Model to use
`timeout`	No	`5m`	Maximum execution time

Timeout Format

30s - 30 seconds
5m - 5 minutes
1h - 1 hour

EXIT CODES

Code	Meaning
`0`	Success
`1`	Codex error
`2`	Codex CLI not found
`124`	Timeout exceeded

OUTPUT

Both stdout and stderr are merged for capture:

generate-code:
  tool: codex
  arguments:
    prompt: "Write a function to parse CSV files"
  output: var(generated_code)

EXAMPLES

Simple Prompt

explain-code:
  tool: codex
  arguments:
    prompt: "Explain what this function does: {{ file(./src/parser.js) }}"

Code Generation

generate-tests:
  tool: codex
  arguments:
    prompt: |
      Generate unit tests for this class:

      {{ file(./src/UserService.ts) }}
  output: file(./tests/UserService.test.ts)

With Model Selection

complex-task:
  tool: codex
  arguments:
    prompt: "Refactor this code to use async/await"
    model: gpt-4

Error Handling

codex-task:
  tool: codex
  arguments:
    prompt: "Analyze this codebase for security issues"
    timeout: 10m
  on-error:
    2: codex-not-installed
    124: handle-timeout
    _: general-error
  next: process-results

codex-not-installed:
  tool: bash
  arguments:
    command: |
      echo "Codex CLI not found. Install with: npm install -g @openai/codex"
      exit 1

INSTALLATION

The Codex CLI must be installed separately:

npm install -g @openai/codex

Configure authentication according to OpenAI’s documentation.

WORKING DIRECTORY

The tool runs in the project root directory, giving Codex access to the full project context.