ralph

Ralph - Autonomous Software Development Plugin

Ralph is a Claude Code plugin that implements Geoffrey Huntley's "Ralph Wiggum as a software engineer" technique for autonomous software development using fresh context per iteration.

What is Ralph?

Ralph is inspired by Geoffrey Huntley's insight that you can achieve autonomous software development by giving an AI agent:

1. Fresh context every iteration - No memory between work cycles
2. One task at a time - Single focus prevents scope creep
3. Simple, repeatable process - 9 steps executed consistently
4. Trust in eventual consistency - Multiple simple iterations beat one complex attempt

The name "Ralph Wiggum" (from The Simpsons) represents this philosophy: simple, focused, consistent execution without overthinking. Ralph doesn't need to remember the big picture - he just needs clear instructions for the current task.

Phase 1 vs Phase 2

Phase 1 (This Implementation): Interactive Mode

This is a Claude Code plugin using native agent features:

• Skills orchestrate the iteration loop from the main session
• Ralph-worker agent executes tasks with Sonnet 4.5
• Ralph-oracle agent provides deep reasoning with Opus 4.5 + extended thinking
• User interaction at 10-iteration checkpoints
• Full integration with Claude Code's tool ecosystem

Phase 2 (Future): Full Autonomy

Future standalone CLI tool with:

• Background loops running independently
• Cross-session state management
• No human intervention required
• Persistent daemon mode

Phase 1 provides immediate value while validating the core technique. Phase 2 will scale it to true autonomy.

Installation

# Add the marketplace
/plugin marketplace add stavarengo/ralph-wiggum-loop

# Install Ralph
/plugin install ralph@ralph-marketplace

# Initialize in your project
/ralph:init

Quick Start

# 1. Initialize Ralph in your project
/ralph:init

# 2. Customize the templates (optional)
# Edit docs/ai/ralph/PROMPT.md - Ralph's iteration instructions
# Edit docs/ai/ralph/AGENTS.md - Your build/test commands
# Edit docs/ai/ralph/fix_plan.md - Your task list

# 3. Start autonomous development
/ralph:start

# Ralph will now:
# - Pick tasks from fix_plan.md (highest priority first)
# - Implement, test, document, commit each task
# - Continue until complete or you stop it

# 4. Stop when needed
/ralph:stop

Skills Reference

Ralph provides 5 skills for different stages of autonomous development:

/ralph:init - Initialize Ralph

Sets up Ralph in your project by creating the directory structure and copying templates.

What it does:

• Creates docs/ai/ralph/ directory
• Copies 3 templates: PROMPT.md, fix_plan.md, AGENTS.md
• Creates CLAUDE.md symlink for auto-loading context
• Initializes status.json for iteration tracking
• Updates .gitignore to exclude Ralph's working directory

After initialization, your project will have:

your-project/
├── docs/ai/ralph/
│   ├── PROMPT.md      # Ralph's iteration instructions
│   ├── fix_plan.md    # Task list and priorities
│   ├── AGENTS.md      # Build/test instructions + learnings
│   └── status.json    # Iteration tracking
├── CLAUDE.md          # Symlink → docs/ai/ralph/AGENTS.md
└── .gitignore         # Updated to exclude docs/ai/ralph/

Next steps:

1. Edit fix_plan.md to add your tasks (in priority order)
2. Edit AGENTS.md to add your build/test commands
3. Run /ralph:start to begin autonomous development

/ralph:start - Start Autonomous Loop

Begins the autonomous iteration loop that runs continuously until all tasks are complete.

What it does:

• Validates prerequisites (PROMPT.md, fix_plan.md, status.json exist)
• Clears any existing stop signal
• Updates status to 'running'
• Enters main loop:
  • Spawns ralph-worker for one iteration
  • Checks for completion signals (RALPH_COMPLETE, RALPH_BLOCKED)
  • Checks for stop signal (.ralph_stop)
  • Prompts user every 10 iterations for confirmation
  • Continues until complete/blocked/stopped

Example output:

Ralph started. Beginning autonomous iteration loop...

=========================================
Starting iteration 1
=========================================
Iteration 1: Implemented user authentication
- Files changed: src/auth.ts, tests/auth.test.ts
- Tests: PASS (all 12 tests passing)
- Next: Add password reset flow

=========================================
Starting iteration 2
=========================================
Iteration 2: Implemented password reset flow
- Files changed: src/reset.ts, tests/reset.test.ts
- Tests: PASS (all 15 tests passing)
- Next: RALPH_COMPLETE

RALPH_COMPLETE signal detected. All tasks complete!

Ralph completed successfully!
- Total iterations: 2
- Status: complete
- All tasks in fix_plan.md have been completed.