oimiragieo/ralph-loop

Ralph Loop

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:

1. Dual-mode architecture — Standalone mode (Stop hook) or multi-agent mode (router-managed iteration)
2. RALPH_ACTIVE env var guard — Stop hook only activates when RALPH_ACTIVE=1 is set, preventing host/router trapping
3. State persistence — JSON state file tracks iteration count, timestamps, findings
4. Circuit breaker — Detects repeated failures and exits gracefully
5. Verification-first exit — Completion signal only accepted when validation commands pass
6. 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.

| File | Project Path | Purpose | | --------------- | ------------------------------------------ | ---------------------------------------------------------- | | Stop hook | .claude/hooks/ralph-stop-hook.cjs | Loop controller (stdin -> transcript check -> re-inject) | | Prompt | .claude/ralph/PROMPT.md | Audit/task instructions re-injected each iteration | | State | .claude/context/runtime/ralph-state.json | Iteration count, timestamps, findings count (auto-created) | | Guardrails | .claude/ralph/guardrails.md | Learned lessons from past failures | | Launcher (bash) | .claude/ralph/ralph-audit.sh | Unix/macOS launcher script (sets RALPH_ACTIVE=1) | | Launcher (bat) | .claude/ralph/ralph-audit.bat | Windows launcher script (sets RALPH_ACTIVE=1) | | Settings | .claude/settings.json | Stop hook registration (Mode 1 only) |

Usage

Standalone Mode (Stop Hook)

# 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 activate
export 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:

1. Mission — What the agent must accomplish
2. Scope — Specific areas to audit/fix
3. Validation commands — Commands that must pass
4. 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:

0. 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.
1. Read stdin (Claude Code transcript JSON)
2. Check stop_hook_active guard (prevent infinite re-triggering)
3. Check if ralph-state.json exists (no state = no active loop)
4. Check transcript for RALPH_AUDIT_COMPLETE_NO_FINDINGS
   • Found → clear state file, exit 0 (allow exit)
5. Load state from ralph-state.json, increment iteration
6. Check for progress signal (RALPH_ITERATION_COMPLETE)
7. Check circuit breaker (findings count stuck for N iterations)
8. Check max iterations (default: 25)
   • Reached → clear state, exit 0 (force stop)
9. Save updated state
10. Read PROMPT.md and write to stdout as JSON { decision: 'block', reason: <prompt> }
11. Exit 0 (with block decision in stdout)

Exit Codes

| Code | Meaning | | ---- | ----------------------------------------------- | | 0 | Allow exit (complete, max iterations, or error) | | 2 | Block exit, stdout fed back as next prompt |

Configuration

Environment Variables

| Variable | Default | Description | | --------------------------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------- | | RALPH_ACTIVE | (unset) | Must be 1 to activate the Stop hook. Set by launcher scripts. Without this, the hook is a no-op. | | RALPH_MAX_ITERATIONS | 25 | Maximum loop iterations | | RALPH_COMPLETION_SIGNAL | RALPH_AUDIT_COMPLETE_NO_FINDINGS | String that signals completion | | RALPH_CIRCUIT_BREAKER_THRESHOLD | 3 | Consecutive iterations with unchanged findings count before circuit breaker trips |

State File Schema

{
  "iteration": 3,
  "startedAt": "2026-02-28T10:00:00Z",
  "lastRunAt": "2026-02-28T10:15:00Z",
  "lastFindingsCount": 5
}

TDD State Schema (for TDD-mode loops)

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:

{
  "scenarios": [
    {
      "id": "sc-001",
      "description": "routing-guard blocks Write on creator paths",
      "status": "pending|red|green|refactored"
    }
  ],
  "completedScenarios": [
    {
      "id": "sc-001",
      "evidenceCommand": "node --test tests/hooks/routing-guard.test.cjs",
      "redEvidence": "AssertionError: expected exit code 2, got 0",
      "greenEvidence": "✓ routing-guard blocks Write (4ms)",
      "passedAt": "2026-03-12T10:00:00Z"
    }
  ],
  "currentScenario": "sc-002",
  "evidenceLog": [
    {
      "scenarioId": "sc-001",
      "phase": "red|green|refactored",
      "output": "<verbatim test runner output>",
      "timestamp": "2026-03-12T09:58:00Z"
    }
  ]
}

TDD Session Resumption: On each loop iteration, before picking a scenario:

const tddState = JSON.parse(
  fs.readFileSync('.claude/context/runtime/tdd-state.json', 'utf-8') || '{}'
);
const completedIds = (tddState.completedScenarios || []).map(s => s.id);
const remaining = (tddState.scenarios || []).filter(s => !completedIds.includes(s.id));
if (remaining.length === 0) {
  // All scenarios complete — emit RALPH_AUDIT_COMPLETE_NO_FINDINGS
  console.log('RALPH_AUDIT_COMPLETE_NO_FINDINGS');
  process.exit(0);
}
const nextScenario = remaining[0];

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

1. Binary criteria — "All tests pass" not "code is good"
2. Validation commands — Include runnable commands (pnpm test, pnpm lint)
3. Findings format — Structured findings with severity, file, status
4. Idempotent — Prompt must work correctly on any iteration (read state first)
5. 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

1. NO LOOP WITHOUT VERIFICATION — Completion signal must be backed by passing validation commands
2. NO LOOP WITHOUT MAX ITERATIONS — Every loop must have a safety cap
3. NO LOOP WITHOUT STATE FILE — Progress must be persisted to survive context resets
4. NO LOOP WITHOUT GUARDRAILS — Failures must be recorded to prevent repetition
5. 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.