> ## Documentation Index
> Fetch the complete documentation index at: https://wiggum.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent mode

> Autonomous backlog processing — from GitHub issues to merged PRs with zero intervention.

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

```bash theme={null}
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](/using-wiggum/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`:

```bash theme={null}
# 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:

```bash theme={null}
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](/commands/agent) for all flags.