# Ralph Loop

Run, monitor, resume, merge, and debug Ralph loops.

- Repository: https://github.com/mikeyobrien/ralph-orchestrator (3190 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add mikeyobrien/ralph-orchestrator --skill ralph-loop -g -a claude-code -y`
Codex: `npx skills add mikeyobrien/ralph-orchestrator --skill ralph-loop -g -a codex -y`
Cursor: `npx skills add mikeyobrien/ralph-orchestrator --skill ralph-loop -g -a cursor -y`
Gemini CLI: `npx skills add mikeyobrien/ralph-orchestrator --skill ralph-loop -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add mikeyobrien/ralph-orchestrator`

## Description

Run, monitor, resume, merge, and debug Ralph loops. Use this skill whenever the user asks to operate `ralph run` or `ralph loops`, inspect loop state, recover suspended loops, analyze diagnostics, or unblock merge queue issues.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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