---
name: Ralph Loop
slug: ralph-loop
category: AI Engineering
description: "Ralph Loop operates Ralph loops from the CLI: start or continue runs with the right configs, inspect state and diffs, resume suspended loops, and merge or discard completed worktree loops. Use it whenever you need to run, monitor, recover, or debug Ralph loops and merge queues."
github: "https://github.com/mikeyobrien/ralph-orchestrator/tree/main/skills/ralph-loop"
language: Rust
stars: 3099
forks: 285
install: "npx degit https://github.com/mikeyobrien/ralph-orchestrator/tree/main/skills/ralph-loop ~/.claude/skills/ralph-loop"
installs_to: ~/.claude/skills/ralph-loop
source_path: skills/ralph-loop/SKILL.md
collection_size: 20
category_size: 2451
collection_url: "https://dirskills.com/collections/mikeyobrien/ralph-orchestrator"
added: 2026-08-17T07:09:06.648Z
last_synced: 2026-08-17T07:09:06.648Z
canonical_url: "https://dirskills.com/skills/ralph-loop"
---

# Ralph Loop

Ralph Loop operates Ralph loops from the CLI: start or continue runs with the right configs, inspect state and diffs, resume suspended loops, and merge or discard completed worktree loops. Use it whenever you need to run, monitor, recover, or debug Ralph loops and merge queues.

**Install:**

```bash
npx degit https://github.com/mikeyobrien/ralph-orchestrator/tree/main/skills/ralph-loop ~/.claude/skills/ralph-loop
```

## README

# Ralph Loop

Use this skill to operate Ralph loops from the outside.

## Use This Skill For

- Starting or continuing a Ralph run with the right `-c` and `-H` inputs
- Inspecting loop state, worktrees, logs, history, and diffs
- Resuming a hook-suspended loop
- Merging or discarding completed worktree loops
- Debugging unexpected loop behavior with current diagnostics files

## Workflow

1. Start with `ralph loops list` or `ralph loops list --json` to establish the
   current state.
2. If the user wants execution, run `ralph run ...` with the right core config
   and hats source.
3. If the loop is stuck or suspicious, inspect `logs`, `history`, and `diff`
   before changing state.
4. If the loop is suspended, read `.ralph/suspend-state.json` and use
   `ralph loops resume <id>`.
5. If a loop is queued or in `needs-review`, inspect the diff first, then use
   `merge`, `process`, `retry`, or `discard` as appropriate.
6. Use diagnostics when you need detailed evidence about hats, events, tool
   calls, parse errors, or performance.

## Guardrails

- Prefer the CLI over direct edits to `.ralph` state files.
- Treat tasks and memories as the canonical runtime systems; do not center
  scratchpad as the primary state model.
- Inspect diffs before merging.
- Only remove lock or queue artifacts when the underlying process is confirmed
  dead.
- Manual edits under `.ralph/` are last-resort recovery steps and should be
  called out explicitly when used.

## Read These References When Needed

- For command recipes and operator flows: `references/commands.md`
- For diagnostics files and suspend-state details: `references/diagnostics.md`