> ## 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

> Autonomously process your GitHub backlog — pick issues, generate specs, run Ralph loops, review diffs, and auto-merge PRs.

```bash theme={null}
wiggum agent [options]
```

Agent mode reads your GitHub backlog, selects the highest-priority issue, generates a spec, runs the full [Ralph loop](/using-wiggum/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

<Steps>
  <Step title="Read backlog">
    Fetches open GitHub issues and ranks them by priority labels (`P0` > `P1` > `P2`) and dependency order.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Generate spec">
    Creates an implementation-ready spec from the issue context (title, body, labels) — same quality as `wiggum new`.
  </Step>

  <Step title="Run Ralph loop">
    Executes the full 5-phase Ralph loop: planning → implementation → E2E testing → verification → PR review.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## Flags

<ParamField path="--labels" type="string">
  Comma-separated GitHub labels to filter issues. Only issues with at least one matching label are processed.

  ```bash theme={null}
  wiggum agent --labels bug,P0
  ```
</ParamField>

<ParamField path="--issues" type="string">
  Comma-separated issue numbers to process. Restricts agent to specific issues instead of the full backlog.

  ```bash theme={null}
  wiggum agent --issues 42,38,15
  ```
</ParamField>

<ParamField path="--max-items" type="number">
  Stop after completing this many issues.

  ```bash theme={null}
  wiggum agent --max-items 3
  ```
</ParamField>

<ParamField path="--max-steps" type="number">
  Stop after this many orchestrator steps (tool calls). Safety limit to prevent runaway execution.
</ParamField>

<ParamField path="--review-mode" type="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
</ParamField>

<ParamField path="--model" type="string">
  Override the AI model for the orchestrator.
</ParamField>

<ParamField path="--dry-run" type="boolean" default="false">
  Simulate the full workflow without executing loops or creating PRs. Useful for testing issue selection and spec generation.
</ParamField>

<ParamField path="--stream" type="boolean" default="false">
  Force headless streaming output. Skips the TUI even in interactive terminals.
</ParamField>

<ParamField path="--diagnose-gh" type="boolean" default="false">
  Run GitHub connectivity checks to debug authentication or permission issues.
</ParamField>

## Routing behavior

| Condition                | Output                             |
| ------------------------ | ---------------------------------- |
| Interactive TTY (not CI) | TUI with live orchestrator display |
| `--stream` flag          | Headless streaming output          |
| Non-TTY or CI            | Headless streaming output          |

## Examples

<CodeGroup>
  ```bash Interactive theme={null}
  wiggum agent
  ```

  ```bash Process P0 bugs only theme={null}
  wiggum agent --labels P0,bug --review-mode merge
  ```

  ```bash CI pipeline theme={null}
  wiggum agent --stream --review-mode merge --max-items 5
  ```

  ```bash Specific issues theme={null}
  wiggum agent --issues 42,38 --review-mode auto
  ```

  ```bash Dry run theme={null}
  wiggum agent --dry-run --labels P1
  ```
</CodeGroup>

## Feature state assessment

Before processing each issue, the agent assesses the current state and decides the right action:

| State                       | Action                                     |
| --------------------------- | ------------------------------------------ |
| No branch, no spec          | Start fresh — generate spec, run full loop |
| Spec exists, no branch      | Generate implementation plan, run loop     |
| Branch exists, partial work | Resume implementation from last checkpoint |
| PR already open             | Comment on existing PR, skip to next issue |
| PR already merged           | Check remaining tasks, close issue if done |

This prevents duplicate work and ensures the agent picks up where it left off after interruptions.