["Always define clear completion criteria before starting","Set max iterations to prevent runaway loops","Use verification commands as completion gates","Check guardrails.md before each iteration"]
Autonomous iteration loop for Claude Code with dual-mode support. Named after the Ralph Wiggum technique popularized in the Claude Code community (Dec 2025 - Feb 2026).
Purpose
Enable Claude Code to work autonomously on well-defined tasks until genuine completion, without manual re-prompting. The skill provides:
RALPH_ACTIVE env var guard — Stop hook only activates when RALPH_ACTIVE=1 is set, preventing host/router trapping
State persistence — JSON state file tracks iteration count, timestamps, findings
Circuit breaker — Detects repeated failures and exits gracefully
Verification-first exit — Completion signal only accepted when validation commands pass
Guardrails — Accumulated lessons from past failures prevent repeated mistakes
When to Use
Well-defined tasks with clear, testable success criteria
Iterative work (get tests passing, fix lint errors, audit codebase)
Overnight or background autonomous runs
Multi-phase audits with structured findings logs
When NOT to Use
Subjective goals ("make the code better")
One-off fixes that don't need iteration
Tasks requiring human judgment at each step
Exploratory research without clear deliverables
Architecture — Two Modes
Mode 1: Standalone (Stop Hook)
For single-session use. The Stop hook keeps the session alive until completion. Requires RALPH_ACTIVE=1 env var (set by the launcher scripts).
User runs ralph-audit.sh/bat (sets RALPH_ACTIVE=1)
|
v
Claude works on task (reads PROMPT.md)
|
v
Claude attempts to exit
|
v
Stop hook intercepts (ralph-stop-hook.cjs)
|
+-- RALPH_ACTIVE != '1'? --> YES --> exit(0) immediately (no-op)
|
+-- Completion signal found? --> YES --> Clear state, exit(0)
|
+-- Max iterations reached? --> YES --> Clear state, exit(0)
|
+-- NO --> Increment iteration, save state, re-inject prompt, block exit
Mode 2: Router-Managed (Multi-Agent) -- Primary mode for agent-studio
This is the primary mode within agent-studio. The router manages iteration by spawning and re-spawning QA agents via Task(). No Stop hook is involved -- the router itself controls the loop lifecycle. The state file at .claude/context/runtime/ralph-state.json within agent-studio tracks iteration progress.
Router receives /ralph-loop command
|
v
Router spawns QA agent with audit prompt via Task()
|
v
QA agent completes, reports findings via TaskUpdate()
|
v
Router checks audit state file (.claude/context/runtime/ralph-state.json)
|
+-- RALPH_AUDIT_COMPLETE_NO_FINDINGS? --> Done
|
+-- RALPH_ITERATION_COMPLETE? --> Spawn another QA agent
|
+-- Max iterations? --> Report and stop
Why two modes: Stop hooks fire on the host session, not on subagents. In multi-agent setups (like agent-studio), the Stop hook would trap the router. The RALPH_ACTIVE guard ensures the hook is a no-op unless explicitly activated by a standalone launcher. In agent-studio, Mode 2 is used exclusively -- the router orchestrates iteration without any Stop hook registration.
Components
Skill Bundle (included in this skill directory)
File
Relative Path
Purpose
Main script
scripts/main.cjs
CLI for status/reset/config of ralph loop state
Pre-execute hook
hooks/pre-execute.cjs
Input validation before skill execution
Post-execute hook
hooks/post-execute.cjs
Output validation after skill execution
Input schema
schemas/input.schema.json
Input validation schema
Output schema
schemas/output.schema.json
Output contract schema
Implementation template
templates/implementation-template.md
PROMPT.md and launcher templates
Skill rule
rules/ralph-loop.md
Skill-specific rules
Project-Level Files (set up per-project by the user)
These files are NOT part of the skill bundle. They live in the hosting project's .claude/ directory and must be created/configured by the user or via the implementation template.
# From your project's workspace root — sets RALPH_ACTIVE=1 automatically
.claude/ralph/ralph-audit.sh # Unix/macOS
.claude\ralph\ralph-audit.bat # Windows
Manual Standalone Start
# Must set RALPH_ACTIVE=1 yourself for the Stop hook to activateexport RALPH_ACTIVE=1
claude --print-output-format text < .claude/ralph/PROMPT.md
Multi-Agent Mode (Router-Managed)
Use the /ralph-loop command within agent-studio, or have the router spawn QA agents with the audit prompt. The router manages iteration; no Stop hook is involved.
Custom Prompt
Create a custom PROMPT.md with:
Mission — What the agent must accomplish
Scope — Specific areas to audit/fix
Validation commands — Commands that must pass
Completion condition — The exact completion signal string
Completion Signals
Signal
Meaning
RALPH_AUDIT_COMPLETE_NO_FINDINGS
All validations pass, zero open findings
RALPH_ITERATION_COMPLETE: N findings remain
Progress made, N findings still open
Stop Hook Protocol
The stop hook (ralph-stop-hook.cjs) follows this protocol:
GUARD 0: Check RALPH_ACTIVE env var — if not '1', exit 0 immediately (no stdin read, no file checks, no-op). This is the critical protection that prevents the hook from trapping the host/router session.
When using ralph-loop for TDD workflows, use a separate TDD-specific state file at .claude/context/runtime/tdd-state.json. This schema tracks per-scenario RED/GREEN evidence across session interruptions:
Critical rule: Never re-execute scenarios already in completedScenarios. The evidenceLog is append-only — each phase (red/green/refactored) adds a new entry. Circuit breaker trips if currentScenario is unchanged for 3+ iterations.
Integration with TDP: When spawning the developer agent for a TDD loop iteration, extract the red evidence from evidenceLog and inject verbatim into the spawn prompt (see tdd skill — Test-Driven Prompting pattern).
Writing Effective Prompts
Structure
# Mission
One-line directive.
## Before Doing Anything
Step 1: Read previous findings (if exists)
Step 2: Load context/skills
## Scope
Numbered list of areas to audit/fix.
## Validation Commands
Commands that must pass for completion.
## Findings Log
Where to write findings (path + format).
## Completion Condition
Exact signal strings and when to use each.
Best Practices
Binary criteria — "All tests pass" not "code is good"
Validation commands — Include runnable commands (pnpm test, pnpm lint)
Findings format — Structured findings with severity, file, status
Idempotent — Prompt must work correctly on any iteration (read state first)
Context management — Include token-saver invocation for long sessions
Guardrails Pattern
The guardrails.md file accumulates "Signs" — lessons learned from failures:
### Sign: [Name]-**Trigger**: When this applies
-**Instruction**: What to do
-**Added after**: What failure taught this
Agents should read guardrails.md at the start of each iteration and add new Signs when they encounter novel failure modes.
Enforcement Hooks
Input validated against schemas/input.schema.json before execution.
Output contract defined in schemas/output.schema.json.
Anti-Patterns
Anti-Pattern
Why It Fails
Correct Approach
No max iterations
Infinite loop burns tokens
Always set maxIterations (default 25)
Vague completion criteria
Agent claims "done" prematurely
Use binary pass/fail validation commands
No state persistence
Progress lost on context reset
Write findings to file, read at iteration start
Stop hook without RALPH_ACTIVE guard
Traps host/router session in multi-agent setups
Check RALPH_ACTIVE=1 before any other logic
Running standalone mode from router
Router gets trapped by Stop hook
Use router-managed iteration (Mode 2) instead
No guardrails
Same mistakes repeated each iteration
Maintain guardrails.md with learned Signs
Iron Laws
NO LOOP WITHOUT VERIFICATION — Completion signal must be backed by passing validation commands
NO LOOP WITHOUT MAX ITERATIONS — Every loop must have a safety cap
NO LOOP WITHOUT STATE FILE — Progress must be persisted to survive context resets
NO LOOP WITHOUT GUARDRAILS — Failures must be recorded to prevent repetition
RALPH_ACTIVE GUARD FIRST — Stop hook must check RALPH_ACTIVE=1 env var before reading stdin, checking files, or any other logic. This is the primary protection against trapping the host/router.
Memory Protocol (MANDATORY)
Before starting:
Read .claude/context/memory/learnings.md using the Read tool.
Check for:
Previously run ralph loops and their outcomes
Known audit patterns and failure modes
User preferences for iteration limits
After completing:
Loop completed successfully → Append summary to learnings.md
New guardrail discovered → Add Sign to .claude/ralph/guardrails.md
Architecture decision → Append to decisions.md
ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.
