Autonomous AI agent orchestration using the Ralph Wiggum technique - keeps AI in a loop until tasks complete. Use when mentioning "ralph", "ralph wiggum", "orchestrator", "long-running", "autonomous agent", "loop until done", "overnight coding", "evolutionary development", "multi-iteration", "hands-off automation".
/plugin marketplace add terrylica/cc-skills/plugin install terrylica-ralph-tools-plugins-ralph-tools@terrylica/cc-skillsThis skill is limited to using the following tools:
references/prompt-templates.mdreferences/troubleshooting.mdRalph Orchestrator is the production implementation of the Ralph Wiggum technique - a deceptively simple yet powerful approach to autonomous AI development. At its core, Ralph embodies a single idea: put an AI agent in a loop and let it iterate until the task is done.
The technique was created by Geoffrey Huntley and is named after Ralph Wiggum's famous quote: "Me fail English? That's unpossible!" Ralph embraces deterministic failure in an undeterministic world - it fails predictably but in ways you can address.
As Huntley defines it, Ralph is fundamentally a Bash loop:
while :; do cat PROMPT.md | claude ; done
Ralph Orchestrator takes this elegantly simple concept and wraps it with production-grade features: checkpointing, metrics, error recovery, cost management, and multi-agent support.
What makes Ralph transformative is its evolutionary nature. Each iteration:
This creates an emergent development process where complex systems evolve from simple specifications. The AI doesn't need to solve everything at once - it iterates, learns from failures, and progressively builds toward the goal.
| Scenario | Why Ralph Excels |
|---|---|
| Greenfield projects | Start with a spec, wake up to working code |
| Large refactoring | Systematic, exhaustive changes across codebase |
| Test generation | Iteratively build comprehensive test suites |
| Documentation | Generate docs that evolve with understanding |
| Bug hunts | Persistent debugging across multiple attempts |
| API implementations | Build endpoints one by one with verification |
| Data pipelines | Complex transformations with validation |
Is the task well-defined with clear success criteria?
├── No → Refine spec first, then consider Ralph
└── Yes → Does it require multiple iterations/steps?
├── No → Use Claude Code directly
└── Yes → Will you be away (sleeping, meeting, etc.)?
├── No → Claude Code may be faster for active work
└── Yes → Ralph is perfect - set it and forget it
# Clone and install
git clone https://github.com/mikeyobrien/ralph-orchestrator.git
cd ralph-orchestrator
uv sync
# Or install globally
pip install ralph-orchestrator
# Initialize a new project
ralph init
# Edit PROMPT.md with your task
# Then run
ralph run
# Or use inline prompt
ralph run -p "Build a REST API for user management with tests"
| Command | Description |
|---|---|
ralph init | Initialize project with PROMPT.md and ralph.yml |
ralph run | Start the orchestration loop |
ralph status | Check current progress and metrics |
ralph clean | Clean workspace and reset state |
ralph run --dry-run | Test without executing |
The PROMPT.md file is your contract with Ralph. A well-crafted prompt dramatically improves results.
# Task: [Clear, Specific Name]
## Objective
[1-2 sentences describing the end goal]
## Context
[Background the AI needs to understand the task]
## Requirements
1. [Specific, measurable requirement]
2. [Another requirement]
3. [...]
## Constraints
- [Technical limitation]
- [Resource constraint]
- [Style/convention requirement]
## Success Criteria
The task is complete when:
- [ ] [Verifiable outcome 1]
- [ ] [Verifiable outcome 2]
- [ ] [Verifiable outcome 3]
## Progress Tracking
<!-- Ralph updates this section -->
- Status: Not Started
- Current: N/A
- Completed: None
---
The orchestrator will continue iterations until limits are reached.
Be Specific, Not Vague
# Bad
Build a website
# Good
Build a Flask web app with:
- User registration (email + password)
- SQLite database using SQLAlchemy
- Bootstrap 5 UI with responsive design
- Unit tests with pytest (>80% coverage)
Include Examples
## Example API Response
GET /users/123
{
"id": 123,
"email": "user@example.com",
"created_at": "2025-01-15T10:30:00Z"
}
Define Clear Boundaries
## Constraints
- Python 3.11+ only
- No external API calls
- Must work offline
- Follow PEP 8 style guide
- All functions require type hints
ralph [OPTIONS] [COMMAND]
Commands:
init Initialize a new Ralph project
run Run the orchestrator (default)
status Show current status and metrics
clean Clean up workspace
prompt Generate structured prompt from ideas
Options:
-c, --config FILE Configuration file (ralph.yml)
-a, --agent TYPE Agent: claude, q, gemini, acp, auto
-P, --prompt-file FILE Prompt file path (default: PROMPT.md)
-p, --prompt-text TEXT Inline prompt (overrides file)
-i, --max-iterations N Maximum iterations (default: 100)
-t, --max-runtime SECONDS Maximum runtime (default: 14400)
-v, --verbose Enable verbose output
-d, --dry-run Test mode without execution
--max-tokens N Maximum total tokens (default: 1000000)
--max-cost DOLLARS Maximum cost in USD (default: 50.0)
--checkpoint-interval N Git checkpoint frequency (default: 5)
--retry-delay SECONDS Retry delay on errors (default: 2)
--no-git Disable git checkpointing
--no-archive Disable prompt archiving
--no-metrics Disable metrics collection
--acp-agent COMMAND ACP agent command (default: gemini)
--acp-permission-mode MODE Permission handling:
- auto_approve: Approve all (CI/CD)
- deny_all: Deny all (testing)
- allowlist: Pattern-based approval
- interactive: Manual approval
| Task Type | Iterations | Time | Cost (Claude) | Cost (Q/Gemini) |
|---|---|---|---|---|
| Simple script | 5-10 | 2-5 min | $0.05-0.10 | $0.01-0.02 |
| Web API | 20-40 | 10-20 min | $0.50-1.50 | $0.10-0.30 |
| Full application | 50-100 | 30-60 min | $2-10 | $0.50-2 |
| Large refactor | 100+ | 1-4 hours | $5-50 | $1-10 |
| Documentation | 15-30 | 5-15 min | $0.30-0.80 | $0.05-0.15 |
# Start conservative
ralph run --max-cost 5.0 --max-iterations 20
# Scale up after validation
ralph run --max-cost 50.0 --max-iterations 100
# Use tiered agents
ralph run -a q --max-cost 2.0 # Research phase
ralph run -a claude --max-cost 20.0 # Implementation
ralph run -a q --max-cost 2.0 # Testing phase
The real measure is not API cost but developer time saved:
| Scenario | Manual Estimate | Ralph Cost | Time Saved | ROI |
|---|---|---|---|---|
| REST API | 8 hours ($400) | $5 | 7.5 hours | 7,900% |
| Test suite | 4 hours ($200) | $3 | 3.8 hours | 6,567% |
| Documentation | 3 hours ($150) | $2 | 2.9 hours | 7,400% |
Task: Build multiple products for hackathon submission overnight Approach: Multiple Ralph loops running in parallel Result: 6 repositories shipped in a single session Key Insight: Parallel execution multiplies productivity exponentially
Task: Build complete MVP for client contract Traditional Estimate: $50,000 outsourcing cost Actual Cost: $297 in API credits Outcome: Successful delivery with 16,835% cost savings Key Insight: Detailed specification + iterative refinement = quality results
Task: Create a complete esoteric programming language Duration: 3+ months of continuous iteration Result: Working language and compiler that the AI invented and programs in Key Insight: Long-running loops can achieve complex emergent behavior beyond training data
# Ralph Orchestrator Configuration
agent: auto # claude, q, gemini, acp, auto
prompt_file: PROMPT.md # Task description file
max_iterations: 100 # Maximum loop iterations
max_runtime: 14400 # 4 hours in seconds
verbose: false # Enable verbose output
# Per-agent settings
adapters:
claude:
enabled: true
timeout: 300 # 5 minutes per iteration
q:
enabled: true
timeout: 300
gemini:
enabled: true
timeout: 300
acp:
enabled: true
timeout: 300
tool_permissions:
agent_command: gemini
permission_mode: auto_approve
| Agent | Best For | Context Window | Speed | Cost |
|---|---|---|---|---|
| Claude | Complex logic, nuanced tasks | 200K tokens | Medium | Higher |
| Q Chat | AWS integrations, quick tasks | Variable | Fast | Lower |
| Gemini | Large codebases, research | 2M tokens | Medium | Lower |
| ACP | Custom agents, specialized tools | Varies | Varies | Varies |
# Complex task needing understanding
ralph run -a claude
# Large codebase, lots of context
ralph run -a gemini
# Quick iterations, cost-sensitive
ralph run -a q
# Overnight run with fallback
ralph run -a auto # Auto-detects best available
Ralph succeeds because it embraces fundamental principles:
As Geoffrey Huntley noted: "It's better to fail predictably than succeed unpredictably."
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.