Skip to main content
wiggum agent [options]
Agent mode reads your GitHub backlog, selects the highest-priority issue, generates a spec, runs the full Ralph loop, reviews the diff against the spec, and auto-merges when checks pass — then moves to the next issue. Zero intervention required.

​
How it works

1

Read backlog

Fetches open GitHub issues and ranks them by priority labels (P0 > P1 > P2) and dependency order.
2

Assess feature state

For each issue, determines the right action: start fresh, generate a plan, resume an existing implementation, skip if already shipped, or comment on an existing PR.
3

Generate spec

Creates an implementation-ready spec from the issue context (title, body, labels) — same quality as wiggum new.
4

Run Ralph loop

Executes the full 5-phase Ralph loop: planning → implementation → E2E testing → verification → PR review.
5

Review and merge

Reviews the diff against the spec. In merge mode, auto-merges the PR when all checks pass, then moves to the next issue.

​
Flags

​
--labels
string
Comma-separated GitHub labels to filter issues. Only issues with at least one matching label are processed.
wiggum agent --labels bug,P0
​
--issues
string
Comma-separated issue numbers to process. Restricts agent to specific issues instead of the full backlog.
wiggum agent --issues 42,38,15
​
--max-items
number
Stop after completing this many issues.
wiggum agent --max-items 3
​
--max-steps
number
Stop after this many orchestrator steps (tool calls). Safety limit to prevent runaway execution.
​
--review-mode
string
default:"manual"
Controls what happens after loop completion:
  • manual — Creates PR, stops for human review
  • auto — Auto-reviews the diff, creates PR
  • merge — Auto-reviews, creates PR, and auto-merges when checks pass
​
--model
string
Override the AI model for the orchestrator.
​
--dry-run
boolean
default:"false"
Simulate the full workflow without executing loops or creating PRs. Useful for testing issue selection and spec generation.
​
--stream
boolean
default:"false"
Force headless streaming output. Skips the TUI even in interactive terminals.
​
--diagnose-gh
boolean
default:"false"
Run GitHub connectivity checks to debug authentication or permission issues.

​
Routing behavior

ConditionOutput
Interactive TTY (not CI)TUI with live orchestrator display
--stream flagHeadless streaming output
Non-TTY or CIHeadless streaming output

​
Examples

wiggum agent

​
Feature state assessment

Before processing each issue, the agent assesses the current state and decides the right action:
StateAction
No branch, no specStart fresh — generate spec, run full loop
Spec exists, no branchGenerate implementation plan, run loop
Branch exists, partial workResume implementation from last checkpoint
PR already openComment on existing PR, skip to next issue
PR already mergedCheck remaining tasks, close issue if done
This prevents duplicate work and ensures the agent picks up where it left off after interruptions.