Use this skill when:

User asks to "start a ralph loop" or "run ralph"
User wants autonomous iteration on a task
User says "keep working until done" or "iterate until complete"
A complex task would benefit from multiple iterations
User explicitly requests Claude to invoke ralph

How to Start a Ralph Loop

Run this bash command:

"$HOME/.claude/plugins/cache/claude-code-plugins/ralph-wiggum/1.0.0/scripts/setup-ralph-loop.sh" \
  "<TASK_DESCRIPTION>" \
  --max-iterations <N> \
  --completion-promise "<PROMISE_TEXT>"

Parameters

Parameter	Required	Default	Description
TASK_DESCRIPTION	Yes	-	The task to work on
--max-iterations	Recommended	unlimited	Safety limit (use 20-100)
--completion-promise	Recommended	null	Text to output when truly done

Example Invocations

Simple task:

"$HOME/.claude/plugins/cache/claude-code-plugins/ralph-wiggum/1.0.0/scripts/setup-ralph-loop.sh" \
  "Fix all TypeScript type errors" \
  --max-iterations 50 \
  --completion-promise "ALL_ERRORS_FIXED"

Complex refactor:

"$HOME/.claude/plugins/cache/claude-code-plugins/ralph-wiggum/1.0.0/scripts/setup-ralph-loop.sh" \
  "Migrate all API handlers to the new v2 pattern" \
  --max-iterations 100 \
  --completion-promise "MIGRATION_COMPLETE"

How the Loop Works

Claude runs the setup script → Creates state file at .claude/ralph-loop.local.md
Claude works on the task → Normal operation
Claude tries to exit → Stop hook intercepts
Hook re-injects prompt → Claude continues with same task
Repeat until:
- Max iterations reached, OR
- Claude outputs <promise>PROMISE_TEXT</promise>

Completing the Loop

When the task is genuinely complete, output the completion promise in XML tags:

<promise>ALL_ERRORS_FIXED</promise>

CRITICAL RULES:

Only output the promise when the statement is TRUE
Do NOT lie to exit the loop
Do NOT output false promises even if stuck
Trust the process - if stuck, iterate and try differently

Canceling a Loop

If needed, cancel with:

rm .claude/ralph-loop.local.md

Or use: /ralph-wiggum:cancel-ralph

Best Practices

Always set --max-iterations - Prevents runaway costs (50-100 is reasonable)
Use specific completion promises - "ALL_TESTS_PASS" not "DONE"
Include success criteria in task - Be explicit about what "done" means
Monitor progress - head -10 .claude/ralph-loop.local.md
Start small - Test with 3-5 iterations first

Cost Warning

Autonomous loops consume tokens rapidly. A 50-iteration loop can cost $50-100+ in API usage. Always use --max-iterations as a safety net.

Why This Skill Exists

The official ralph-wiggum plugin requires users to run /ralph-loop commands. This skill enables Claude to invoke loops directly, enabling:

Claude-initiated iteration on complex tasks
Programmatic loop triggers from other skills/agents
Automated workflows without manual commands

ralph-invoke

Ralph Invoke Skill

Prerequisites

Triggers