Run headless work with codex exec

Understand the approach

Headless or non-interactive work uses codex exec instead of opening the interactive terminal interface. It fits a stable task with clear inputs and an output another process or person can inspect. The source uses Claude's print mode; those flags and output contracts are not interchangeable. In Codex, progress normally goes to standard error and the final agent message to standard output; --json produces a JSON Lines event stream.

A scripted run still needs the correct repository, available tools, authentication, and permissions. Current documentation gives codex exec a read-only default, and this lesson makes that boundary explicit. Use a Git practice repository and public or fictional data. Do not add broad-access flags, skip repository checks, or create CI credentials simply to complete a first exercise. Process success and a convincing final message are different observations.

Choose the output contract before integrating a pipeline. Use a final message for a human-readable summary, JSONL for events, or a supported output schema when a downstream consumer needs a fixed final shape. Validate file existence, parseability, and semantic correctness. Missing data must remain distinguishable from an empty result. A testable headless workflow also states what happens on unavailable tools, denied operations, interrupted execution, and stale inputs.

Start with a manual consumer

Read the first output yourself before writing a program that acts on it. A summary may be formatted correctly yet cite a nonexistent script or overlook a conflicting document. Once the workflow is reliable, define a machine-readable schema and validate it separately from factual accuracy. Keep downstream writes disabled until the receiving system, target record, and authorization are explicit. This reduces the risk of turning a minor analytical error into an external change.

Try it step by step

1. Use the generated package root, existing authentication and a Git-initialized scratch directory. Read the fixed prompt and final-output schema.
2. Run the documented codex exec pipeline if you intend a real inference run. Keep event JSONL, final JSON and stderr in separate fresh files.
3. Inspect the actual process exit and turn.completed/turn.failed/error events before consuming the final file; never reuse a stale result from a failed run.
4. Validate the final object against both schema and deterministic fixture facts. Empty findings for missing-checks are incorrect even when JSON parses.
5. Record the actual model/session/input checkpoint and limits. The app/IDE interactive workflow and offline expected result are separate from this shell run.

A useful starting example

Illustration · adapt before use.

& {
  $ErrorActionPreference = 'Stop'
  $outputDirectory = Join-Path (Get-Location).Path ('review-output-' + [guid]::NewGuid().ToString('N'))
  New-Item -ItemType Directory -Path $outputDirectory | Out-Null
  $finalOutput = Join-Path $outputDirectory 'review.actual.json'
  $eventOutput = Join-Path $outputDirectory 'review.events.jsonl'
  $errorOutput = Join-Path $outputDirectory 'review.stderr.txt'
  $reviewPrompt = Get-Content -Raw workflows/review-prompt.txt
  $codexCommand = @(Get-Command codex -CommandType Application -ErrorAction Stop)[0]
  try {
    $ErrorActionPreference = 'Continue'
    $reviewPrompt | & $codexCommand.Source --ask-for-approval never exec --sandbox read-only --json --output-schema workflows/review-result.schema.json --output-last-message $finalOutput - > $eventOutput 2> $errorOutput
    $reviewExit = $LASTEXITCODE
  } finally { $ErrorActionPreference = 'Stop' }
  if ($reviewExit -ne 0) { throw "Codex failed ($reviewExit); inspect $errorOutput. Final output was not accepted." }
  if (-not (Test-Path -LiteralPath $finalOutput -PathType Leaf)) { throw 'No fresh final output was written.' }
  node workflows/validate-artifact.cjs review $finalOutput --expected-fixture missing-checks
  if ($LASTEXITCODE -ne 0) { throw 'The actual answer failed factual/schema validation.' }
  Write-Output "Verified actual result: $finalOutput"
}

Check your result

• The actual pipeline separates events, final output and diagnostics, with an inspected process/turn outcome.
• The final output is complete for the requested missing-checks subject and matches both schema and actual heading evidence.
• No stale output, fabricated response or broad-access flag substitutes for a failed run.

Common mistakes

• Parsing JSONL as one JSON object or assuming a final message proves every requested check ran.
• Copying a CI example that exposes credentials to untrusted build steps or posts results without authorization.