ralph-loop

A Ralph loop consists of:

• Task System - Native Claude Code task management with dependency tracking
• Prompt (prompt.md) - Instructions for each iteration
• Runner (ralph.sh) - Bash script that loops until completion
• Progress (progress.txt) - Execution log
• Knowledge (knowledge.md) - Accumulated learnings

To create a new Ralph loop, gather requirements then run the init script:

```bash

python ~/.claude/skills/ralph-loop/scripts/init_ralph.py

```

Step 1: Gather Requirements

Before creating a loop, clarify these parameters with the user using AskUserQuestion:

Loop Goal:

• What is the global objective of this loop?
• What domain/codebase does it operate on?

Task Structure:

• What kind of tasks/items will be tracked?
• What dependencies exist between tasks?
• What metadata should each task have?

Iteration Process:

• What steps should each iteration perform?
• What tools/commands are needed?
• What files should be read/written?

Acceptance Criteria:

• How to validate a task is completed?
• What checks should pass before marking done?
• Should there be automated validation (tests, builds, typechecks)?

Exit Conditions:

• When should the loop terminate? (all tasks done, specific marker, max iterations)
• What completion marker to use? Default: COMPLETE

Step 2: Select or Create Template

Available templates in ~/.claude/skills/ralph-loop/templates/:

| Template | Use Case |

|----------|----------|

| migration.md | Migrating components, APIs, dependencies |

| exploration.md | Codebase analysis, documentation generation |

| testing.md | Test generation, coverage improvement |

| refactoring.md | Code cleanup, pattern enforcement |

| custom.md | Blank template for unique workflows |

Step 3: Generate Loop Files

After gathering requirements, generate the loop structure:

```bash

python ~/.claude/skills/ralph-loop/scripts/init_ralph.py \

--template migration \

--output ./my-loop \

--goal "Migrate React components from styled-components to Tailwind"

```

Or interactively:

```bash

python ~/.claude/skills/ralph-loop/scripts/init_ralph.py ./my-loop

```

Step 4: Create Tasks Using Task System

After generating the loop, create tasks using the native Task tools:

```

TaskCreate:

subject: "Migrate Button component"

description: "Convert Button from styled-components to Tailwind CSS classes"

activeForm: "Migrating Button component"

```

Set up dependencies between tasks:

```

TaskUpdate:

taskId: "2"

addBlockedBy: ["1"] # Task 2 waits for Task 1

```

Step 5: Run the Loop

```bash

cd

./ralph.sh [max-iterations]

```

Default max iterations: 50

```

/

├── ralph.sh # Executable bash loop

├── prompt.md # Iteration instructions (uses Task tools)

├── progress.txt # Execution log

├── knowledge.md # Accumulated learnings

└── logs/ # Per-run log files

```

The Ralph loop uses Claude Code's native Task management system:

Tools:

• TaskCreate - Create new tasks with subject, description, activeForm
• TaskList - View all tasks with status/owner/blockers
• TaskGet - Fetch full task details by ID
• TaskUpdate - Change status, set dependencies, mark complete

Status values: pending, in_progress, completed

Dependencies:

• blocks - Tasks that cannot start until this one completes
• blockedBy - Tasks that must complete before this one can start

Benefits over JSON backlog:

• Native dependency tracking
• Status validation (can't mark complete if tests fail)
• Parallel agent coordination via owner field
• Progress spinner shows activeForm text

```markdown

# Ralph Agent: {Goal}

• List paths, files, tools

Step 1: Load Context

Use TaskList to get all tasks, read knowledge.md

Step 2: Determine State

Check if all tasks are completed → output COMPLETE

Step 3: Select Target

Use TaskList to find first task with:

• status: "pending"
• blockedBy: empty (no unresolved dependencies)

Use TaskUpdate to set status: "in_progress"

Step 4-N: Execute

Task-specific steps using TaskGet for full details

Final Step: Update

Use TaskUpdate to set status: "completed"

Update progress.txt and knowledge.md

When all tasks completed: COMPLETE

```

After generating the loop, create tasks for the backlog. Example for a migration loop:

```

# Create first task

TaskCreate:

subject: "Migrate Button component"

description: "Convert Button.tsx from styled-components to Tailwind. Update imports, replace styled() calls with className props using Tailwind utilities."

activeForm: "Migrating Button component"

# Create dependent task

TaskCreate:

subject: "Migrate Modal component"

description: "Convert Modal.tsx. Depends on Button migration since Modal uses Button internally."

activeForm: "Migrating Modal component"

# Set dependency

TaskUpdate:

taskId: "2"

addBlockedBy: ["1"]

```

Tip: Use TaskUpdate with addBlockedBy to ensure tasks run in correct order.

1. One task per iteration - Keep iterations focused
2. Clear acceptance criteria - Define what "done" means
3. Use dependencies - Set blockedBy for ordered tasks
4. Incremental commits - Commit after each successful task
5. Knowledge accumulation - Document learnings for future iterations
6. Fail fast - Stop on errors, don't silently continue
7. Idempotent operations - Safe to re-run if interrupted

| Issue | Solution |

|-------|----------|

| Loop never completes | Check completion marker in prompt.md matches ralph.sh |

| Tasks skipped | Verify status field updates in prompt.md |

| Context overflow | Reduce prompt.md size, move details to knowledge.md |

| Permission errors | Ensure ralph.sh has execute permissions |

• [templates/](templates/) - Pre-built loop templates
• [references/patterns.md](references/patterns.md) - Common iteration patterns