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

Phase	Description
Initialize	Agent receives task with autonomy configuration
Execute	Agent works on task, writes state to files
Check	System checks for completion promise in output
Reset	If not done, context clears and loop restarts
Complete	Promise 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,
    }
)

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

CLI Options

Option	Short	Type	Default	Description
--max-iterations	-n	int	10	Maximum loop iterations
--completion-promise	-p	str	None	Text that signals completion
--clear-context	-c	bool	False	Clear chat history between iterations
--timeout	-t	float	None	Timeout in seconds
--model	-m	str	None	LLM model to use
--verbose	-v	bool	False	Show detailed output

Programmatic Options

Option	Type	Default	Description
max_iterations	int	10	Maximum autonomous iterations
completion_promise	str	None	Promise text for completion detection
clear_context	bool	False	Reset context each iteration
timeout_seconds	float	None	Overall 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

Use file-based state for complex tasks

When --clear-context is enabled, ensure your agent writes progress to files (like progress.txt or a task list) so state persists across iterations.

Set appropriate completion promises

Choose unique, unmistakable completion words like TASK_COMPLETE, DONE, or FEATURE_SHIPPED. Avoid common words that might appear accidentally.

Use timeouts for safety

Always set --timeout for production use to prevent runaway loops from consuming excessive resources.

Enable verbose mode for debugging

Use -v when developing new autonomous workflows to understand the agent’s behavior across iterations.

---

Related

Autonomy

Configure autonomous agent behavior

Execution

Control execution limits and patterns