Skip to main content
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

PhaseDescription
InitializeAgent receives task with autonomy configuration
ExecuteAgent works on task, writes state to files
CheckSystem checks for completion promise in output
ResetIf not done, context clears and loop restarts
CompletePromise detected or max iterations reached

​
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,
    }
)

result = agent.run_autonomous(
    prompt="Build a calculator app",
    max_iterations=10,
    timeout_seconds=300,
    completion_promise="DONE",
    clear_context=True,
)

​
CLI Options

OptionShortTypeDefaultDescription
--max-iterations-nint10Maximum loop iterations
--completion-promise-pstrNoneText that signals completion
--clear-context-cboolFalseClear chat history between iterations
--timeout-tfloatNoneTimeout in seconds
--model-mstrNoneLLM model to use
--verbose-vboolFalseShow detailed output

​
Programmatic Options

OptionTypeDefaultDescription
max_iterationsint10Maximum autonomous iterations
completion_promisestrNonePromise text for completion detection
clear_contextboolFalseReset context each iteration
timeout_secondsfloatNoneOverall timeout limit

​
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

When --clear-context is enabled, ensure your agent writes progress to files (like progress.txt or a task list) so state persists across iterations.
Choose unique, unmistakable completion words like TASK_COMPLETE, DONE, or FEATURE_SHIPPED. Avoid common words that might appear accidentally.
Always set --timeout for production use to prevent runaway loops from consuming excessive resources.
Use -v when developing new autonomous workflows to understand the agent’s behavior across iterations.

Autonomy

Configure autonomous agent behavior

Execution

Control execution limits and patterns