WARNING This library is under active development, primarily using Wiggumizer itself to work through the missing elements. There are currently Documentation inaccuracies, issues with the file parsing logic, strange behaviors that need prompt engineering, and so on. Use at your own risk!

Wiggumizer

Ralph Wiggum style AI coding automation - deterministic imperfection meets eventual consistency.

Wiggumizer is a CLI tool that automates the Ralph coding technique - an iterative AI-driven development approach that produces quality code through systematic refinement rather than upfront perfection.

What is Ralph?

The Ralph technique, pioneered by Geoffrey Huntley, is based on a deceptively simple loop:

while :; do cat PROMPT.md | npx --yes @sourcegraph/amp ; done

You write a prompt describing what you want, and the loop iteratively refines your code until it converges to your requirements.

Real-World Success

• $50k contract delivered for $297 in API costs
• Multiple repos built overnight at Y Combinator hackathons
• Novel programming languages created despite not existing in training data

The technique works. Wiggumizer makes it practical.

Quick Start

# Install
npm install -g wiggumizer

# Initialize in your project
cd your-project
wiggumize init

# Create a prompt
echo "Refactor getUserData to use async/await and add error handling" > PROMPT.md

# Run the loop
wiggumize run

# Watch your code converge to the desired state

Full Documentation →

Key Features

🎯 Prompt Template Library

Pre-built templates for common tasks: refactoring, testing, documentation, feature implementation.

🔄 Multi-Provider Support

Works with Claude, GPT, Sourcegraph Amp, Ollama, and local models. Switch providers seamlessly.

🚀 Multi-Repo Orchestration

Run Ralph loops across multiple repositories simultaneously. Coordinate changes across your entire stack.

🎓 Smart Convergence Detection

Automatically recognizes when code has reached the desired state. No more manual loop monitoring.

🛡️ Safety Features

Git integration, syntax validation, test execution, automatic backups. Safe by default.

📝 Change Documentation

Automatic session summary generation with commit messages, PR descriptions, and JIRA updates. Link changes to issues with YAML metadata.

💬 Chat Service Integration

Get notified via Slack or WhatsApp when runs complete or encounter errors. Interactive mode to respond to chat messages.

🧠 Self-Discovery Through Iteration

Unlike other tools that "tell" the AI what was done, Wiggumizer implements the pure Ralph philosophy:

• Constant prompts - The same goal every iteration, forcing deeper engagement
• Git archaeology - Claude reads git log to discover what it did before
• Breadcrumb notes - Claude can create .ralph-notes.md to leave insights for future iterations
• Autonomous learning - Claude must examine files and context to understand its own progress

This creates true iterative learning where each iteration builds meaningfully on the last.

Usage Patterns

Wiggumizer supports different workflows depending on your needs:

Quick Fix (5-20 minutes)

echo "Add error handling to getUserData()" > PROMPT.md
wiggumize run --max-iterations 10
# Review, test, commit - done!

Feature Development (1-3 hours, single session)

# PROMPT.md: "Implement dark mode with theme switcher and persistence"
wiggumize run --max-iterations 30
# Let it converge, review comprehensive changes

Project Evolution (Days/weeks, multiple sessions)

# Day 1: Initial work
echo "Phase 1: Refactor authentication to use JWT" > PROMPT.md
wiggumize run
git commit -am "Phase 1: JWT authentication complete"

# Day 3: Next phase (MANUALLY UPDATE PROMPT.md)
vim PROMPT.md  # Change to "Phase 2: Add OAuth providers"
wiggumize run

Key Principle: Between sessions, manually update PROMPT.md to give the AI new direction. The AI discovers its previous work through git history and .ralph-notes.md, but you control the goal.

What Updates Automatically vs. Manually

Automatic (Wiggumizer modifies these files):

• ✅ PROMPT.md checkboxes - Wiggumizer directly edits PROMPT.md to change - [ ] → - [✅] as work completes
• ✅ .ralph-notes.md - AI leaves notes for next iteration
• ✅ SESSION-SUMMARY.md - Summary of last run (commit messages, PR descriptions)
• ✅ .wiggumizer/iterations/ - Detailed logs

Manual (You control):

• ✋ PROMPT.md content - Core instructions, goals, adding new tasks
• ✋ What to work on next - Deciding direction between sessions
• ✋ When to run vs. commit - Workflow control

Important: PROMPT.md is a living document - Wiggumizer automatically updates checkbox status in the file, but you control everything else.

This keeps you in the driver's seat while letting the AI iterate within your defined boundaries.

Philosophy

Wiggumizer embraces "deterministic imperfection" - the idea that code quality emerges through iteration rather than upfront perfection.

Traditional coding: Think deeply → Code once → Done Ralph coding: Code quickly → Iterate → Converge

This isn't about AI writing perfect code. It's about creating a systematic process that reliably transforms code toward quality through repeated refinement.

Installation

# npm (Node.js)
npm install -g wiggumizer

# pip (Python)
pip install wiggumizer

# cargo (Rust)
cargo install wiggumizer

# Homebrew (macOS/Linux)
brew install wiggumizer

See Installation Guide for detailed instructions.

Documentation

• Quick Start (5 minutes) - Get running fast
• First Project Tutorial - Complete example
• Ralph Philosophy - Why this works
• CLI Reference - All commands
• Prompt Templates - Reusable patterns
• AI Providers - Setup guides
• Troubleshooting - Common issues

View Full Documentation

Example

Here's a real prompt that modernized a legacy authentication module:

# Modernize Authentication Module

File: src/auth/legacy-auth.js

Goals:
1. Convert to ES6+ syntax (const/let, arrow functions, async/await)
2. Replace callbacks with promises
3. Add input validation on all public methods
4. Add comprehensive JSDoc comments
5. Extract hardcoded values to constants
6. Keep 100% backward compatibility

Do NOT:
- Change function names or signatures
- Modify the export structure
- Add external dependencies

Run all existing tests after each change to ensure compatibility.

Result: Converged in 7 iterations. Legacy module fully modernized while maintaining full backward compatibility.

Use Cases

Refactoring:

• Modernize legacy code
• Extract patterns into reusable functions
• Improve code organization

Code Generation:

• Generate tests from existing code
• Create documentation
• Build new features from specs

Code Improvement:

• Add error handling
• Improve security
• Optimize performance
• Add type annotations

Learning:

• Understand unfamiliar codebases
• Learn new patterns and frameworks
• Explore different approaches

AI Providers

Wiggumizer supports two ways to use Claude AI:

Claude API (default)

Uses the Anthropic API directly. Requires an API key and charges based on usage.

export ANTHROPIC_API_KEY=your-api-key-here
wiggumize run --provider claude

Best for:

• Production use
• CI/CD pipelines
• Precise cost tracking
• Advanced retry and rate limiting features

Claude CLI

Uses the claude CLI command, which leverages your Claude Pro or Max subscription instead of API costs.

# Install the Claude CLI
npm install -g @anthropic-ai/claude-cli

# Use it with Wiggumizer
wiggumize run --provider claude-cli

Best for:

• Personal projects
• Heavy usage (fixed monthly cost)
• Claude Pro/Max subscribers
• Simplified setup (no API key management)

Note: The CLI provider has simplified error handling (no automatic retries) but works great for most use cases.

Configuration

Create .wiggumizer.yml in your project:

# Choose your provider
provider: claude  # or 'claude-cli'

# Provider-specific settings
providers:
  claude:
    model: claude-opus-4-5-20251101
    maxTokens: 16384
  claude-cli:
    model: claude-opus-4-5-20251101
    maxTokens: 16384

defaults:
  max_iterations: 20
  convergence_threshold: 0.95

templates:
  directory: ./.wiggumizer/templates

Or use environment variables:

export WIGGUMIZER_PROVIDER=claude
export ANTHROPIC_API_KEY=your-api-key-here

See Configuration Reference for all options.

Chat Service Integration

Wiggumizer can send notifications to external chat services when runs complete or encounter errors. This is useful for long-running jobs where you want to be notified of progress.

Supported Providers

• Slack - Uses the Slack CLI for local workspace integration
• WhatsApp - Uses CLI tools like mudslide for WhatsApp messaging

Usage

# Send notifications to Slack
wiggumize run --chat-provider slack --channel "#dev-notifications"

# Send notifications via WhatsApp
wiggumize run --chat-provider whatsapp --contact "+1234567890"

# Interactive mode - listen and respond to messages
wiggumize listen --chat-provider slack --channel "#random"

Prerequisites

For Slack:

# Install Slack CLI
# See: https://api.slack.com/automation/cli/install

# Authenticate
slack login

For WhatsApp:

# Install mudslide
npm install -g mudslide

# Authenticate (scan QR code)
mudslide login

Configuration

Add to .wiggumizer.yml:

# Chat notifications
chatProvider: slack
channel: "#wiggumizer"

# Or for WhatsApp
# chatProvider: whatsapp
# contact: "+1234567890"
# group: "Dev Team"

Notification Events

1. Successful completion - Summary of work completed (files modified, iterations, duration)
2. Unexpected stoppage - Error notification with reason (rate limit, permission denied, etc.)

Community

• Contributing - Help improve Wiggumizer
• Showcase - Share your success stories
• Template Registry - Share and discover prompts
• GitHub Issues - Report bugs
• Discussions - Get help

License

MIT License - see LICENSE for details.

Acknowledgments

• Geoffrey Huntley - Creator of the Ralph technique
• @sourcegraph/amp - The original Ralph tool
• Anthropic - Claude AI
• OpenAI - GPT models
• All contributors to the Wiggumizer project

Credits

Named after Ralph Wiggum from The Simpsons, whose endearing imperfection inspired the philosophy of "deterministic imperfection leading to eventual consistency."

"I'm a Star Wars!" - Ralph Wiggum

Ready to start? Head to the Quick Start guide and run your first Ralph loop in 5 minutes.