ralph-loop-helper

name	ralph-loop-helper
description	Guide for using /ralph-loop command for long-running autonomous tasks. Use when starting iterative development loops, implementing Bedrock plugins, or running test-fix cycles. (project)
allowed-tools	Read, Bash, Glob, Grep
metadata	{"author":"mineflayer-bedrock","version":"1.0"}

Ralph Loop Helper

Guide users on effectively using /ralph-loop for long-running autonomous tasks in the mineflayer-bedrock project.

Overview

The Ralph Wiggum plugin implements an iterative AI development loop. It uses a Stop hook that intercepts Claude's exit attempts, feeding the same prompt back to continue working until completion criteria are met.

Core mechanism: You run /ralph-loop "task" once. Claude works, tries to exit, the hook blocks it, re-feeds the prompt, and repeats until done.

When to Use

• Implementing a new Bedrock plugin that needs to match Java API
• Running test suites and fixing all failures iteratively
• Large refactoring tasks with clear completion criteria
• Tasks with automatic verification (tests, linters, type checks)
• Greenfield implementations with well-defined requirements

When NOT to Use

• Tasks requiring human judgment or design decisions
• One-shot operations (single file edits, quick fixes)
• Exploratory work with unclear success criteria
• Production debugging requiring careful analysis
• Tasks where you need to review intermediate results

Known Limitations

Multiline Prompts NOT Supported

CLI arguments cannot contain newlines due to Bash security restrictions. These GitHub issues track this:

• Issue #15640: Bash security blocks newlines
• Issue #15712: Command contains newlines error
• Issue #15824: Feature request for file-based prompts

Workaround: Keep prompts single-line or use phased execution (see below).

Exact String Matching Only

--completion-promise uses exact string matching. You cannot use regex or multiple conditions like "SUCCESS OR BLOCKED". Use the <promise>TAG</promise> pattern for clarity.

Token Consumption

Each iteration consumes full context window tokens. A 50-iteration loop on a large codebase can cost $50-100+ in API credits.

Recommended Patterns

1. Always Use --max-iterations

This is your primary safety mechanism. Never rely solely on completion promises.

/ralph-loop "Your task..." --max-iterations 30

2. Use Promise Tags

Wrap completion signals in tags for clear detection:

/ralph-loop "Build feature X. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations 25

3. Include Stuck Handling

Add escape instructions for when Claude gets stuck:

/ralph-loop "Implement feature. After 10 iterations without progress: document blockers, list attempts, suggest alternatives. Output <promise>BLOCKED</promise> if truly stuck, <promise>DONE</promise> if complete." --max-iterations 20

4. Phased Execution for Complex Tasks

Break large tasks into phases instead of one massive prompt:

# Phase 1
/ralph-loop "Phase 1: Create data models. Output <promise>P1_DONE</promise>" --max-iterations 15

# Phase 2
/ralph-loop "Phase 2: Implement API endpoints. Output <promise>P2_DONE</promise>" --max-iterations 20

# Phase 3
/ralph-loop "Phase 3: Add tests, ensure all pass. Output <promise>P3_DONE</promise>" --max-iterations 25

Project-Specific Examples

Implement a Bedrock Plugin

/ralph-loop "Implement inventory.mts Bedrock plugin in lib/bedrockPlugins/ matching the Java API in lib/plugins/inventory.js. Map Bedrock packets to same bot behavior. Run 'npm run mocha_test' after changes. Output <promise>PLUGIN_COMPLETE</promise> when tests pass." --max-iterations 30

Fix Test Failures

/ralph-loop "Run 'npm run test:bedrock'. Fix any failing tests. Do not skip tests. Output <promise>TESTS_PASS</promise> when all tests green." --max-iterations 20

API Compatibility Check

/ralph-loop "Compare lib/bedrockPlugins/health.mts with lib/plugins/health.js. Ensure Bedrock version exposes same API (functions, events, properties). Fix discrepancies. Run tests. Output <promise>API_MATCH</promise> when compatible." --max-iterations 15

Type Error Resolution

/ralph-loop "Run 'npx tsc --noEmit'. Fix all TypeScript errors. Do not use 'any' type. Output <promise>TYPES_CLEAN</promise> when no errors." --max-iterations 25

Cost Awareness

Iterations	Estimated Cost
10-20	$10-25
30-50	$30-75
50+	$50-150+

Tips to reduce costs:

• Start with lower --max-iterations and increase if needed
• Use phased execution to checkpoint progress
• Include clear completion criteria to exit early
• Monitor iteration count in output

Commands Reference

/ralph-loop

Start an iterative development loop.

/ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<text>"

Options:

• --max-iterations <n>: Stop after N iterations (required for safety)
• --completion-promise <text>: Exact string that signals completion

/cancel-ralph

Cancel an active Ralph loop immediately.

/cancel-ralph

Common Mistakes

Mistake	Prevention
No iteration limit	Always use --max-iterations
Vague completion criteria	Use specific, testable conditions
Multiline prompts	Keep single-line or use phases
Relying only on promise	Set iteration limit as backup
Too many iterations at once	Start small, increase if needed

Related Skills

• skill-builder: For creating new Claude Code skills
• create-analyzer: For packet analysis tasks