Skip to main content
wiggum run <feature> [options]
Hands a feature spec to your coding agent and runs the full Ralph loop — five structured phases with independent checkpoints, error handling, and retry logic.

​
How it works

  1. Loads the spec from .ralph/specs/<feature>.md
  2. Combines it with project prompts, guides, and context from .ralph/
  3. Spawns feature-loop.sh which orchestrates the coding agent through five phases:
PhaseWhat happens
PlanningAgent reads the spec and creates a step-by-step implementation plan
ImplementationAgent works through the plan task by task, committing after each
E2E testingAgent runs end-to-end tests, iterates on failures
VerificationAgent re-reads the spec and confirms every requirement is met
PR reviewCreates a pull request (behavior depends on --review-mode)
Each phase can succeed or fail independently. A failure in E2E testing doesn’t require restarting implementation.

​
Flags

​
feature
string
required
Name of the feature spec to run. Must match a file in .ralph/specs/.
​
--cli
string
Coding agent for implementation. Options: claude, codex. Overrides the default set in ralph.config.cjs.
wiggum run my-feature --cli codex
​
--review-cli
string
Coding agent for the review phase. Can differ from the implementation agent.
wiggum run my-feature --cli codex --review-cli claude
​
--worktree
boolean
default:"false"
Run in a git worktree for isolation. Creates a separate working directory so the loop doesn’t interfere with your current work. Recommended for parallel feature development.
​
--resume
boolean
default:"false"
Resume from the last checkpoint if a previous run was interrupted. Skips completed phases.
​
--review-mode
string
default:"manual"
What happens after the loop completes:
  • manual — Creates a PR and stops for human review
  • auto — Auto-reviews the diff against the spec, then creates the PR
  • merge — Auto-reviews, creates PR, and auto-merges when CI checks pass
​
--model
string
AI model for the coding agent. Options depend on your provider (e.g., opus, sonnet for Anthropic).
​
--max-iterations
number
default:"10"
Maximum number of implementation iterations. Each iteration picks the next task from the plan, writes code, and commits.
​
--max-e2e-attempts
number
default:"5"
Maximum number of E2E test retries.

​
TUI monitoring

When run in an interactive terminal, wiggum shows a live RunScreen with:
  • Phase progress — Each phase shows status (pending, active, completed, failed) with duration
  • Iteration counter — Current iteration out of max (e.g. 3/10)
  • Activity feed — Real-time stream of what the coding agent is doing
  • Token tracking — Input/output token counts and cache metrics
  • Task checklist — Implementation plan tasks with completion status

​
Background mode

Press Esc to background the loop and return to the wiggum shell. The loop continues running. Re-attach with: 
wiggum monitor my-feature

​
Completion summary

When the loop finishes, the RunScreen shows:
  • Phase durations
  • Final iteration count
  • File changes summary
  • Commit history
  • PR link (if created)

​
Examples

wiggum
# then type /run add-dark-mode in the TUI