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

# run

> Run the autonomous Ralph loop — plan, implement, test, verify, and create a PR.

```bash theme={null}
wiggum run <feature> [options]
```

Hands a feature spec to your coding agent and runs the full [Ralph loop](/using-wiggum/ralph-loop) — five structured phases with independent checkpoints, error handling, and retry logic.

## How it works

1. Loads the spec from `.ralph/specs/<feature>.md`
2. Combines it with project prompts, guides, and context from `.ralph/`
3. Spawns `feature-loop.sh` which orchestrates the coding agent through five phases:

| Phase              | What happens                                                        |
| ------------------ | ------------------------------------------------------------------- |
| **Planning**       | Agent reads the spec and creates a step-by-step implementation plan |
| **Implementation** | Agent works through the plan task by task, committing after each    |
| **E2E testing**    | Agent runs end-to-end tests, iterates on failures                   |
| **Verification**   | Agent re-reads the spec and confirms every requirement is met       |
| **PR review**      | Creates a pull request (behavior depends on `--review-mode`)        |

Each phase can succeed or fail independently. A failure in E2E testing doesn't require restarting implementation.

## Flags

<ParamField path="feature" type="string" required>
  Name of the feature spec to run. Must match a file in `.ralph/specs/`.
</ParamField>

<ParamField path="--cli" type="string">
  Coding agent for implementation. Options: `claude`, `codex`. Overrides the default set in `ralph.config.cjs`.

  ```bash theme={null}
  wiggum run my-feature --cli codex
  ```
</ParamField>

<ParamField path="--review-cli" type="string">
  Coding agent for the review phase. Can differ from the implementation agent.

  ```bash theme={null}
  wiggum run my-feature --cli codex --review-cli claude
  ```
</ParamField>

<ParamField path="--worktree" type="boolean" default="false">
  Run in a git worktree for isolation. Creates a separate working directory so the loop doesn't interfere with your current work. Recommended for parallel feature development.
</ParamField>

<ParamField path="--resume" type="boolean" default="false">
  Resume from the last checkpoint if a previous run was interrupted. Skips completed phases.
</ParamField>

<ParamField path="--review-mode" type="string" default="manual">
  What happens after the loop completes:

  * `manual` — Creates a PR and stops for human review
  * `auto` — Auto-reviews the diff against the spec, then creates the PR
  * `merge` — Auto-reviews, creates PR, and auto-merges when CI checks pass
</ParamField>

<ParamField path="--model" type="string">
  AI model for the coding agent. Options depend on your provider (e.g., `opus`, `sonnet` for Anthropic).
</ParamField>

<ParamField path="--max-iterations" type="number" default="10">
  Maximum number of implementation iterations. Each iteration picks the next task from the plan, writes code, and commits.
</ParamField>

<ParamField path="--max-e2e-attempts" type="number" default="5">
  Maximum number of E2E test retries.
</ParamField>

## TUI monitoring

When run in an interactive terminal, wiggum shows a live RunScreen with:

* **Phase progress** — Each phase shows status (pending, active, completed, failed) with duration
* **Iteration counter** — Current iteration out of max (e.g. `3/10`)
* **Activity feed** — Real-time stream of what the coding agent is doing
* **Token tracking** — Input/output token counts and cache metrics
* **Task checklist** — Implementation plan tasks with completion status

### Background mode

Press **Esc** to background the loop and return to the wiggum shell. The loop continues running. Re-attach with:

```bash theme={null}
wiggum monitor my-feature
```

### Completion summary

When the loop finishes, the RunScreen shows:

* Phase durations
* Final iteration count
* File changes summary
* Commit history
* PR link (if created)

## Examples

<CodeGroup>
  ```bash Interactive (recommended) theme={null}
  wiggum
  # then type /run add-dark-mode in the TUI
  ```

  ```bash Headless with defaults theme={null}
  wiggum run add-dark-mode
  ```

  ```bash Isolated worktree with auto-merge theme={null}
  wiggum run add-dark-mode --worktree --review-mode merge
  ```

  ```bash Resume interrupted run theme={null}
  wiggum run add-dark-mode --resume
  ```

  ```bash Use Codex for implementation, Claude for review theme={null}
  wiggum run add-dark-mode --cli codex --review-cli claude
  ```

  ```bash Extended iterations theme={null}
  wiggum run add-dark-mode --max-iterations 20 --max-e2e-attempts 10 --model opus
  ```
</CodeGroup>