Ralph Wiggum - Long-Running Development Loops

Long-running iterative development loops with pacing control.

When to Use

• Complex tasks requiring multiple iterations

• Tasks with many discrete steps that build on each other

• Work that benefits from periodic reflection

Do NOT use for simple one-shot tasks or quick fixes.

Agent Tool

Call ralph_start to begin a loop on yourself:

ralph_start({ name: "loop-name", taskContent: "# Task\n\n## Goals\n- Goal 1\n\n## Checklist\n- [ ] Item 1\n- [ ] Item 2", maxIterations: 50, // Default: 50 itemsPerIteration: 3, // Optional: suggest N items per turn reflectEvery: 10, // Optional: reflect every N iterations useSubagents: true, // Optional: delegate each task to subagent subagentAgent: "default" // Optional: subagent name (default: 'default') })

Loop Behavior

• Task content is saved to .ralph/<name>.md

• Each iteration: work on task, update file

• Call ralph_done tool to proceed to next iteration

• When complete: output <promise>COMPLETE</promise>

• Loop ends on completion or max iterations (default 50)

User Commands

• /ralph start <name|path>

• Start a new loop

• /ralph resume <name>

• Resume loop

• /ralph stop

• Pause loop (when agent idle)

• /ralph-stop

• Stop active loop (idle only)

• /ralph status

• Show loops

• /ralph list --archived

• Show archived loops

• /ralph archive <name>

• Move loop to archive

• /ralph clean [--all]

• Clean completed loops

• /ralph cancel <name>

• Delete loop

• /ralph nuke [--yes]

• Delete all .ralph data

During streaming: press ESC to interrupt, send a normal message to resume, and run /ralph-stop when idle to end the loop.

Task File Format

Task Title

Brief description.

Goals

• Goal 1
• Goal 2

Checklist

• Item 1
• Item 2
• Completed item

Notes

(Update with progress, decisions, blockers)

Subagent Mode

Delegate each checklist task to a separate subagent thread:

/ralph start my-tasks --use-subagents --subagent-agent default

How it works:

• Extracts uncompleted checklist items (- [ ] Task )

• Each task is delegated to a fresh subagent thread (1 task = 1 subagent)

• Subagent completes task and marks it done (- [x] Task )

• Main loop orchestrates and tracks progress

• Automatic retry logic for failures (2 attempts)

Benefits:

• Fresh context per task (no pollution)

• Isolated execution (failures don't cascade)

• Clear task tracking and progress reporting

• Suitable for independent, discrete tasks

When to use:

• Tasks are independent (no shared state)

• Each task is substantial enough for separate execution

• You want clean separation between tasks

• Task list is well-defined upfront

Best Practices

• Clear checklist: Break work into discrete items

• Update as you go: Mark items complete, add notes

• Reflect when stuck: Use reflection to reassess approach (normal mode)

• Complete properly: Only output completion marker when truly done

• Subagent mode: Use for independent tasks with clear boundaries