> 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:

``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.

$3

- $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

`bash


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

$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 progress

This 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 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

`bash


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:

`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-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:

`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: 16384

defaults:
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 mudslide

Authenticate (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"

``

$3

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.