Ralph Wiggum style AI coding automation - iterative code refinement with LLMs
npm install wiggumizer> 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!
> 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.
The Ralph technique, pioneered by Geoffrey Huntley, is based on a deceptively simple loop:
``bash`
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.
- $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.
`bashInstall
npm install -g wiggumizer
Key Features
$3
Pre-built templates for common tasks: refactoring, testing, documentation, feature implementation.$3
Works with Claude, GPT, Sourcegraph Amp, Ollama, and local models. Switch providers seamlessly.$3
Run Ralph loops across multiple repositories simultaneously. Coordinate changes across your entire stack.$3
Automatically recognizes when code has reached the desired state. No more manual loop monitoring.$3
Git integration, syntax validation, test execution, automatic backups. Safe by default.$3
Automatic session summary generation with commit messages, PR descriptions, and JIRA updates. Link changes to issues with YAML metadata.$3
Get notified via Slack or WhatsApp when runs complete or encounter errors. Interactive mode to respond to chat messages.$3
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 progressThis creates true iterative learning where each iteration builds meaningfully on the last.
Usage Patterns
Wiggumizer supports different workflows depending on your needs:
$3
`bash
echo "Add error handling to getUserData()" > PROMPT.md
wiggumize run --max-iterations 10
Review, test, commit - done!
`$3
`bash
PROMPT.md: "Implement dark mode with theme switcher and persistence"
wiggumize run --max-iterations 30
Let it converge, review comprehensive changes
`$3
`bash
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.$3
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 logsManual (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
`bash
npm (Node.js)
npm install -g wiggumizerpip (Python)
pip install wiggumizercargo (Rust)
cargo install wiggumizerHomebrew (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
Example
Here's a real prompt that modernized a legacy authentication module:
`markdown
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:
$3
Uses the Anthropic API directly. Requires an API key and charges based on usage.`bash
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
$3
Uses the claude CLI command, which leverages your Claude Pro or Max subscription instead of API costs.`bash
Install the Claude CLI
npm install -g @anthropic-ai/claude-cliUse 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:`yaml
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: 16384defaults:
max_iterations: 20
convergence_threshold: 0.95
templates:
directory: ./.wiggumizer/templates
`Or use environment variables:
`bash
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.
$3
- Slack - Uses the Slack CLI for local workspace integration
- WhatsApp - Uses CLI tools like
mudslide for WhatsApp messaging$3
`bash
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"
`$3
For Slack:
`bash
Install Slack CLI
See: https://api.slack.com/automation/cli/install
Authenticate
slack login
`For WhatsApp:
`bash
Install mudslide
npm install -g mudslideAuthenticate (scan QR code)
mudslide login
`$3
Add to
.wiggumizer.yml:`yaml
Chat notifications
chatProvider: slack
channel: "#wiggumizer"Or for WhatsApp
chatProvider: whatsapp
contact: "+1234567890"
group: "Dev Team"
``1. Successful completion - Summary of work completed (files modified, iterations, duration)
2. Unexpected stoppage - Error notification with reason (rate limit, permission denied, etc.)
- Contributing - Help improve Wiggumizer
- Showcase - Share your success stories
- Template Registry - Share and discover prompts
- GitHub Issues - Report bugs
- Discussions - Get help
MIT License - see LICENSE for details.
- 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
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.