Standardmäßig ist der Prompt ausgewählt, der zuerst die Quelle prüft. Sie können zu einem direkten Befehl wechseln oder eine lokale Kopie herunterladen.
Quelldateien prüfen
Lesen Sie SKILL.md und alle von SkillsMP angezeigten Begleitdateien, bevor Sie sich für eine Installation entscheiden.
Mit Codex oder Claude installieren Kopieren Sie diesen Prompt, fügen Sie ihn in Codex, Claude oder einen anderen Assistant ein und lassen Sie die Skill-Seite prüfen und installieren.
Ein direkter Befehl überspringt den Prüf-Prompt. Prüfen Sie die Quelle, bevor Sie ihn ausführen.
["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.
