Ralph Wiggum Autonomous Task Loop

Keep Claude working on a task autonomously until it reaches a defined completion state.

How It Works

1. Start: Create a loop state file with the task prompt and completion criteria
2. Iterate: Claude works on the task
3. Check: At exit, the Stop hook checks if the task is complete
4. Continue: If not complete, the prompt is re-injected (up to max iterations)
5. Done: When complete (or max iterations hit), Claude is allowed to exit

Two Completion Strategies

Strategy 1: Promise-Based (Simple)

Claude outputs <promise>TASK_COMPLETE</promise> in its response to signal completion.

Example task prompt:
"Process all files in /Needs_Action.
When all items are processed and moved to /Done, output: <promise>TASK_COMPLETE</promise>"

Strategy 2: File-Movement-Based (Gold Tier)

The Stop hook watches for a specific task file to move to /Done. More reliable because completion is a natural part of the workflow.

Example: Start a loop watching for "TASK_20260223_inbox_sweep" in /Done
When the file appears in /Done, the loop exits naturally.

Usage

Start a Ralph Loop (Promise Strategy)

python
1from ralph_loop import RalphLoop
2
3loop = RalphLoop(vault_path="./vault")
4state = loop.start(
5    prompt="Process all pending items in /Needs_Action. "
6           "For each item, create a plan and move to /Done. "
7           "When ALL items are processed, output: <promise>TASK_COMPLETE</promise>",
8    completion_promise="TASK_COMPLETE",
9    max_iterations=10,
10)
11print(f"Loop started: {state.task_id}")

Start a Ralph Loop (File Movement Strategy)

python
1from ralph_loop import RalphLoop
2
3loop = RalphLoop(vault_path="./vault")
4state = loop.start(
5    prompt="Generate this week's CEO briefing and save to vault/Briefings/. "
6           "Move the trigger file to /Done when complete.",
7    completion_file="TASK_briefing_trigger.md",
8    max_iterations=5,
9)

Check Active Loops

python
1from ralph_loop import RalphLoop
2
3loop = RalphLoop(vault_path="./vault")
4active = loop.get_active_loops()
5for state in active:
6    print(f"Loop {state.task_id}: iteration {state.current_iteration}/{state.max_iterations}")

Stop Hook Configuration

To use the Ralph Wiggum loop, configure the Stop hook in Claude Code settings. The stop hook script at src/ralph_loop.py is called when Claude attempts to exit:

bash
1# In Claude Code settings (settings.json or CLAUDE.md):
2# Add stop hook:
3# python src/ralph_loop.py ./vault

The hook:

• Reads Claude's output from stdin
• Checks for completion promise OR looks for completion file in /Done
• Returns exit code 0 (allow exit) or 1 (block and re-inject prompt)

Security Notes

• Max iterations prevent infinite loops (default: 10)
• All loop state stored in vault/Logs/ralph_*.json — visible audit trail
• Loop state files are deleted when loops complete
• Never loops on destructive operations without human approval first

Example: Complete Inbox Processing Loop

/ralph-loop "Process all items in vault/Needs_Action in priority order (high → medium → low).
For each item:
1. Read the item's frontmatter
2. Create a Plan.md in vault/Plans/
3. If approval needed, create approval request in vault/Pending_Approval/
4. Otherwise, process and move to vault/Done/
When ALL items in vault/Needs_Action have been moved to vault/Done,
output: <promise>TASK_COMPLETE</promise>"
--max-iterations 15