Ralph loops are agent-agnostic

The Ralph loop is a structured autonomous coding methodology — plan, implement, test, verify, PR — that works with any CLI-based coding agent. While Claude Code is the most common choice, Wiggum CLI has tested support for OpenAI’s Codex CLI. Same workflow, same spec format, same five phases — different underlying model.

This tutorial walks you through running Ralph loops with Codex CLI. If you’re new to the Ralph loop concept, read the Claude Code tutorial first — it covers the full workflow in more detail. This tutorial focuses on the Codex-specific setup and configuration differences.

Prerequisites

Codex CLI — Install with npm install -g @openai/codex. You’ll need an OpenAI API key.
Wiggum CLI — The orchestrator that manages the Ralph loop.

$ npm install -g wiggum-cli

A git repository with at least one commit.

Step 1: Initialize your project

wiggum init

The init TUI walks you through six phases: scanning your tech stack, selecting a provider, entering API keys, choosing models, running AI analysis, and generating configuration files. The process is identical to the Claude Code setup — the generated .ralph/ directory and codebase context are agent-agnostic.

During provider selection, choose OpenAI if you want Codex as your default agent. You can also use Anthropic for spec generation (the interview AI) and Codex only for the implementation loop — the provider and coding CLI are configured independently.

Step 2: Configure Codex CLI as your agent

After init, tell Wiggum to use Codex for loop execution:

wiggum config set cli codex

This updates ralph.config.cjs to set codingCli: 'codex'. You can also set the review agent independently:

wiggum config set review-cli codex

Or use Claude Code for reviews and Codex for implementation — mix and match:

wiggum config set cli codex
wiggum config set review-cli claude

Codex-specific configuration

The ralph.config.cjs file has Codex-specific settings:

loop: {
  codingCli: 'codex',            // use Codex for implementation
  reviewCli: 'codex',            // use Codex for review
  codexModel: 'gpt-5.3-codex',  // Codex model
  codexSandbox: 'workspace-write',    // sandbox level
  codexApprovalPolicy: 'on-failure',  // when to prompt for approval
}

Sandbox levels:

read-only — Codex can only read files (safest, but limited)
workspace-write — Codex can read/write files in the project directory (recommended)
danger-full-access — Full filesystem access (use with caution)

Approval policies:

untrusted — Prompt for approval on every action
on-failure — Prompt only when something fails (recommended)
on-request — Prompt only when Codex explicitly asks
never — Fully autonomous, no prompts

Step 3: Generate a spec

wiggum new my-feature

The spec generation process is identical regardless of which coding agent you’ll use for implementation. Wiggum’s AI interview generates markdown specs that are agent-agnostic — they describe what to build, not how a specific agent should build it.

All the same flags work:

wiggum new my-feature --issue #42 --context https://docs.example.com/api

For headless spec generation:

wiggum new my-feature --auto --goals "Add WebSocket notifications with rate limiting"

See the Claude Code tutorial’s spec generation section for the full walkthrough of the interview process — context phase, goals, clarifying questions, and generation.

Step 4: Execute the Ralph loop with Codex

wiggum run my-feature

If you configured Codex as your default CLI in step 2, Wiggum uses it automatically. To override per-run:

wiggum run my-feature --cli codex

The Ralph loop runs the same five phases as with Claude Code:

Planning — Codex reads the spec and produces an implementation plan with a task checklist
Implementation — Codex works through the plan task by task, iterating up to maxIterations (default: 10)
E2E testing — Codex runs end-to-end tests and iterates on failures up to maxE2eAttempts (default: 5)
Verification — Codex re-reads the spec and confirms every requirement is met
PR review — Creates a pull request (behavior depends on --review-mode)

Run flags

All the same flags from Claude Code apply:

Flag	Description
`--cli codex`	Use Codex for this run (overrides config)
`--review-cli codex`	Use Codex for review phase
`--worktree`	Run in an isolated git worktree
`--resume`	Resume from last checkpoint
`--review-mode <mode>`	`manual`, `auto`, or `merge`
`--max-iterations <n>`	Override max implementation iterations
`--max-e2e-attempts <n>`	Override max E2E test attempts

Monitoring

The TUI RunScreen works identically with Codex — phase progress bars, activity feed, iteration counter, token tracking, and task checklist. Background with Esc, re-attach with:

wiggum monitor my-feature

Agent mode with Codex

Agent mode works the same way — just ensure Codex is configured as your default CLI:

wiggum config set cli codex
wiggum agent

Or override per-run:

wiggum agent --stream --review-mode merge --labels P0

Agent mode reads your GitHub backlog, picks issues by priority, generates specs, runs the full Ralph loop with Codex, reviews diffs, and auto-merges when checks pass.

All agent flags apply: --labels, --issues, --max-items, --max-steps, --dry-run, --stream, --diagnose-gh.

Differences from Claude Code

The Ralph loop workflow is identical. The differences are in the underlying agent:

Aspect	Claude Code	Codex CLI
Provider	Anthropic	OpenAI
API key	`ANTHROPIC_API_KEY`	`OPENAI_API_KEY`
Config flag	`--cli claude`	`--cli codex`
Config command	`wiggum config set cli claude`	`wiggum config set cli codex`
Default model	Claude Opus / Sonnet	GPT-5.3 Codex
Sandbox config	`claudePermissionMode`	`codexSandbox` + `codexApprovalPolicy`
Wiggum support	First-class	Tested and compatible

The specs, phase structure, TUI monitoring, and PR workflow are all the same. If you’re already running Ralph loops with Claude Code, switching to Codex is a config change — your existing specs work as-is.

Quick reference

Command	What it does
`wiggum config set cli codex`	Set Codex as default coding agent
`wiggum config set review-cli codex`	Set Codex as default review agent
`wiggum init`	Scan codebase, generate `.ralph/` config
`wiggum new <name>`	AI interview → spec (agent-agnostic)
`wiggum run <name>`	Execute Ralph loop with configured agent
`wiggum run <name> --cli codex`	Override agent for this run
`wiggum run <name> --worktree --resume`	Isolated worktree + resume from checkpoint
`wiggum agent`	Autonomous backlog pipeline
`wiggum monitor <name>`	Re-attach to backgrounded loop
`wiggum sync`	Refresh codebase context

Getting started