Agent mode

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:

Fetches your GitHub issues
Picks the highest-priority unblocked issue
Generates an implementation spec from the issue context
Runs the full Ralph loop (plan → implement → test → verify → PR)
Reviews the diff against the spec
Auto-merges the PR when all checks pass
Moves to the next issue

Priority and selection

The agent ranks issues by:

Priority labels — P0 > P1 > P2 (issues without priority labels are ranked lower)
Dependency order — Issues that block others are processed first
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:

State	What the agent does
Fresh — No branch, no spec	Generates spec from issue context, runs full Ralph loop
Spec exists — No implementation branch	Creates implementation plan, runs loop
Partial work — Branch exists with commits	Resumes implementation from last checkpoint
PR open — Pull request already exists	Comments on the PR, moves to next issue
PR merged — Work already shipped	Closes 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:

Mode	Behavior
`manual` (default)	Creates a PR and stops. You review and merge manually.
`auto`	Auto-reviews the diff against the spec, then creates the PR. You still merge manually.
`merge`	Auto-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

Flag	Purpose
`--stream`	Streams output to stdout (no TUI)
`--review-mode merge`	Auto-merge completed PRs
`--labels P0`	Only process high-priority issues
`--max-items 5`	Stop after 5 completed issues

Safety controls

Flag	Purpose
`--dry-run`	Simulate 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-gh`	Test 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.

Getting started

Using wiggum

Commands

Quick start

Priority and selection

Filtering

Feature state assessment

Review modes

TUI display

Running in CI

Safety controls

Memory and learning

​Quick start

​Priority and selection

​Filtering

​Feature state assessment

​Review modes

​TUI display

​Running in CI

​Safety controls

​Memory and learning

Quick start

Priority and selection

Filtering

Feature state assessment

Review modes

TUI display

Running in CI

Safety controls

Memory and learning