Ralph Orchestrator

An autonomous AI agent orchestration system that implements the "Ralph Wiggum technique"—continuously running AI agents in a loop until tasks complete.

When to Use This Skill

• Automating complex multi-step development tasks
• Running agents autonomously until completion
• Orchestrating multiple AI backends
• Long-running automated workflows
• Tasks requiring persistent state across iterations

How It Works

The Core Loop

1. Read task from PROMPT.md
2. Execute AI agent with current prompt
3. Check for completion signals
4. Repeat until success or limits reached

Completion Signals

The loop ends when:

• Task explicitly marked complete
• Maximum iterations reached
• Runtime limit exceeded
• Token/cost limits hit
• Manual interruption

Supported Agents

• Claude (via Claude SDK)
• Gemini
• Q Chat
• Kiro CLI
• ACP-compliant agents (extensible)

Auto-detection identifies installed agents.

Setup

1. Install

pip install ralph-orchestrator

2. Create Task File

Create PROMPT.md with your task:

# Task: Implement User Authentication

## Requirements
- JWT-based authentication
- Password hashing with bcrypt
- Login/logout endpoints
- Token refresh mechanism

## Completion Criteria
- All tests passing
- Documentation updated
- Security review complete

3. Configure (ralph.yml)

agent: claude          # Preferred agent
max_iterations: 50     # Iteration limit
max_runtime: 3600      # Seconds
checkpoint_interval: 5  # Git commits every N iterations

permissions:
  allow_web_search: true
  allow_file_write: true

4. Run

ralph run

Key Features

State Persistence

• Git-based checkpointing
• Progress saved at intervals
• Recovery from interruptions
• Full history tracking

Agent Scratchpad

Maintains context across iterations:

# Scratchpad

## Progress
- [x] Set up project structure
- [x] Implemented JWT generation
- [ ] Password hashing
- [ ] API endpoints

## Notes
- Using bcrypt library for hashing
- Token expiry set to 24 hours

Error Recovery

• Exponential backoff on failures
• Automatic retries
• Graceful degradation
• Clear error reporting

Security

• API key masking in logs
• Sensitive data protection
• Sandboxed execution options
• Audit logging

Example Workflow

Task: Build REST API

PROMPT.md:

Build a REST API for a todo list application.

Requirements:
- CRUD operations for todos
- User authentication
- PostgreSQL database
- FastAPI framework
- Full test coverage

Mark complete when:
- All endpoints working
- Tests passing
- README updated

Execution:

$ ralph run

[Iteration 1/50] Agent: claude
> Setting up project structure...
> Created: main.py, requirements.txt, tests/

[Iteration 2/50] Agent: claude
> Implementing database models...
> Created: models.py, database.py

[Iteration 3/50] Agent: claude
> Building CRUD endpoints...
...

[Iteration 12/50] Agent: claude
> All tests passing. Task complete!

✓ Completed in 12 iterations (23 minutes)

Configuration Options

Option	Default	Description
agent	auto	Preferred agent
max_iterations	100	Iteration limit
max_runtime	3600	Seconds
max_tokens	null	Token budget
max_cost	null	Cost limit ($)
checkpoint_interval	10	Git save frequency

Best Practices

1. Clear Completion Criteria: Define explicit success conditions
2. Reasonable Limits: Set appropriate iteration/time bounds
3. Incremental Tasks: Break large tasks into stages
4. Regular Checkpoints: Enable git-based recovery
5. Monitor Progress: Watch iterations for stuck loops

Troubleshooting

Agent stuck in loop:

• Add clearer completion criteria
• Reduce task complexity
• Check for contradictory requirements

Rate limiting:

• Increase delay between iterations
• Use multiple agent backends
• Set token budgets

Recovery needed:

• Checkpoints auto-restore
• Use ralph resume to continue
• Check .ralph/ for state