What problem does it solve?
Persistence loop. Keep iterating on a task until it's resolved, with a circuit breaker for safety. Different from /loop (which is time-based) — ralph runs the same agent repeatedly until a goal is met.
Core Features & Use Cases
- Use When: Task has a clear completion signal but iteration count is unknown; you want to progressively refine results.
- Do Not Use When: You require time-based polling or a single-shot operation.
- Iron Rules:
- Completion signal must be defined upfront.
- Circuit breaker: stop after 5 iterations OR after 3 identical failures.
- State persisted between iterations.
- Never silently spin — emit progress every iteration.
- Workflow:
- Iteration 1: Run agent, check completion, record attempts and results, increment counter.
- Iteration 2..N: Run with accumulated state; continue until completion or breaker.
- On max iterations or repeated failures: Stop and escalate with full state.
- Output:
Per iteration, emit a structured log with iteration number, goal, attempted actions, result, and current state. Final report saved to workspace/development/debug/[C]ralph-{topic}-{date}.md.
Quick Start
Initiate a ralph loop by defining a clear completion signal and the initial task, then let it iterate until the signal is met or a circuit breaker halts progress.