Ralph Loops

Run agents in autonomous loops with fresh context and file-based persistence

Ralph Loops enable agents to work autonomously through iterative execution cycles, using file-based state persistence and fresh context windows to prevent context degradation.

What is Ralph?

Ralph is an autonomous AI agent loop pattern that emphasizes “naive persistence” – the agent keeps trying until it succeeds. Named after the character Ralph Wiggum from The Simpsons, it embodies a simple but effective philosophy: clear the context, read the state from files, make progress, and repeat.

Key Principles:

• Fresh Context: Each iteration starts with a clean LLM context window
• File-Based State: Progress persists through files and Git history, not chat memory
• Completion Promises: Agent signals task completion via explicit markers
• Doom Loop Detection: Prevents repetitive, non-productive cycles

Quick Start

1. Basic Loop

   praisonai loop "Build a REST API for user management" -n 5

2. With Completion Promise

   praisonai loop "Refactor the authentication module" -p DONE -v

   The agent will include <promise>DONE</promise> in its response when complete.

3. With Context Clearing

   praisonai loop "Implement feature X" -p COMPLETE -c -n 20

   Clears chat history between iterations, forcing file-based state management.

How It Works

Configuration Options

from praisonaiagents import Agent

agent = Agent(
    name="loop_agent",
    instructions="Complete the task autonomously",
    autonomy={
        "max_iterations": 10,
        "completion_promise": "DONE",
        "clear_context": True,
    }
)

# Unified API — start() uses autonomy config automatically!
result = agent.start("Build a calculator app")

CLI Options

Programmatic Options

Completion Detection

The agent signals completion by including a promise marker in its output:

<promise>DONE</promise>

This explicit signaling prevents false completions and gives the agent precise control over when to stop iterating.

Exit Conditions:

1. Promise matched: Output contains <promise>{TEXT}</promise> matching the configured promise
2. Max iterations: Reached the iteration limit
3. Timeout: Exceeded the time limit
4. Doom loop: Detected repetitive non-productive actions
5. User interrupt: Ctrl+C cancellation

Common Patterns

Long-Running Development Tasks

# Build a complete feature with 20 iterations and 10-minute timeout
praisonai loop "Implement user authentication with JWT" \
  -p FEATURE_COMPLETE \
  -c \
  -n 20 \
  -t 600 \
  -v

Debugging Sessions

# Debug with verbose output and completion signal
praisonai loop "Find and fix the memory leak in the cache module" \
  -p BUG_FIXED \
  -v

Refactoring Tasks

# Refactor with context clearing for clean iterations
praisonai loop "Refactor database layer to use async/await" \
  -p REFACTORED \
  -c \
  -n 15

Best Practices

Related