Ralph Invoke Skill

Allows Claude to directly start Ralph-Wiggum autonomous loops without user commands.

Prerequisites

The ralph-wiggum plugin must be installed and enabled:

/plugin install ralph-wiggum@claude-code-plugins
/plugin enable ralph-wiggum@claude-code-plugins

Triggers

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

1. Claude runs the setup script → Creates state file at .claude/ralph-loop.local.md
2. Claude works on the task → Normal operation
3. Claude tries to exit → Stop hook intercepts
4. Hook re-injects prompt → Claude continues with same task
5. 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

1. Always set --max-iterations - Prevents runaway costs (50-100 is reasonable)
2. Use specific completion promises - "ALL_TESTS_PASS" not "DONE"
3. Include success criteria in task - Be explicit about what "done" means
4. Monitor progress - head -10 .claude/ralph-loop.local.md
5. 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