Skip to main content
Agent mode is wiggum’s fully autonomous workflow. Instead of running commands one at a time, the agent reads your GitHub backlog and processes issues end-to-end: selecting, specifying, implementing, testing, reviewing, and merging — then moving to the next issue.

​
Quick start

wiggum agent --review-mode merge
This starts the agent, which:
  1. Fetches your GitHub issues
  2. Picks the highest-priority unblocked issue
  3. Generates an implementation spec from the issue context
  4. Runs the full Ralph loop (plan → implement → test → verify → PR)
  5. Reviews the diff against the spec
  6. Auto-merges the PR when all checks pass
  7. Moves to the next issue

​
Priority and selection

The agent ranks issues by:
  1. Priority labels — P0 > P1 > P2 (issues without priority labels are ranked lower)
  2. Dependency order — Issues that block others are processed first
  3. Feature state — Issues with partial work (existing branches) are prioritized for completion

​
Filtering

Narrow the scope with --labels or --issues: 
# Only process bugs labeled P0
wiggum agent --labels P0,bug

# Process specific issues
wiggum agent --issues 42,38,15

​
Feature state assessment

Before processing each issue, the agent determines the current state:
StateWhat the agent does
Fresh — No branch, no specGenerates spec from issue context, runs full Ralph loop
Spec exists — No implementation branchCreates implementation plan, runs loop
Partial work — Branch exists with commitsResumes implementation from last checkpoint
PR open — Pull request already existsComments on the PR, moves to next issue
PR merged — Work already shippedCloses issue if all requirements met
This prevents duplicate work and handles interruptions gracefully.

​
Review modes

The --review-mode flag controls what happens after each loop completes:
ModeBehavior
manual (default)Creates a PR and stops. You review and merge manually.
autoAuto-reviews the diff against the spec, then creates the PR. You still merge manually.
mergeAuto-reviews, creates PR, and auto-merges when all CI checks pass. Fully autonomous.

​
TUI display

In an interactive terminal, agent mode shows a live orchestrator view:
  • Backlog ranking — Which issues were considered and why
  • Issue selection — The chosen issue with reasoning
  • Loop progress — Real-time phase tracking for the current Ralph loop
  • Completion outcomes — Results for each processed issue

​
Running in CI

For headless execution in CI pipelines: 
wiggum agent --stream --review-mode merge --labels P0 --max-items 5
FlagPurpose
--streamStreams output to stdout (no TUI)
--review-mode mergeAuto-merge completed PRs
--labels P0Only process high-priority issues
--max-items 5Stop after 5 completed issues

​
Safety controls

FlagPurpose
--dry-runSimulate the full workflow without executing loops or creating PRs
--max-items <n>Stop after N completed issues
--max-steps <n>Stop after N orchestrator tool calls
--diagnose-ghTest GitHub connectivity and permissions

​
Memory and learning

The agent stores memory across iterations — what worked, what failed, and patterns it discovered. This memory persists in .ralph/LEARNINGS.md and informs future runs. Over time, the agent gets better at generating specs and implementing features for your specific codebase. See the full agent command reference for all flags.