# π§ Ralph Wiggum
> Autonomous AI coding with spec-driven development
[](LICENSE)
β οΈ **Use at your own risk.** This tool grants AI agents significant autonomy over your codebase and system. Review all changes and use in isolated environments when possible.
## Quick Start
### Install as Agent Skill (New!)
```bash
# Using Vercel's add-skill
npx add-skill fstandhartinger/ralph-wiggum
# Using OpenSkills
openskills install fstandhartinger/ralph-wiggum
```
### Full Setup with Interview
**AI Agent? Start Here:**
> Read and execute [INSTALLATION.md](INSTALLATION.md) for a guided setup with interactive interview.
**Human Developer? Start Here:**
> Read [INSTALL.md](INSTALL.md) for manual setup instructions.
---
## What is Ralph Wiggum?
Ralph Wiggum (in this flavour) combines **Geoffrey Huntley's original iterative bash loop** with **SpecKit-style specifications** for fully autonomous AI-assisted software development.
### Key Features
- π **Iterative Self-Correction** β Each loop picks ONE task, implements it, verifies, and commits
- π **Spec-Driven Development** β Professional specifications with clear acceptance criteria
- π― **Completion Verification** β Agent only outputs `DONE` when criteria are 100% met
- π§ **Fresh Context Each Loop** β Every iteration starts with a clean context window
- π **Shared State on Disk** β `IMPLEMENTATION_PLAN.md` persists between loops
---
## How It Works
Based on [Geoffrey Huntley's methodology](https://github.com/ghuntley/how-to-ralph-wiggum):
```
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β RALPH LOOP β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
β β Orient βββββΆβ Pick Task βββββΆβ Implement β β
β β Read specs β β from Plan β β & Test β β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
β β β
β ββββββββββββββββββββββββββββββββββββββββββ β
β βΌ β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
β β Verify βββββΆβ Commit βββββΆβ Output DONE β β
β β Criteria β β & Push β β (if passed) β β
β ββββββββββββββββ ββββββββββββββββ ββββββββββββββββ β
β β β
β ββββββββββββββββββββββββββββββββββββββββββ β
β βΌ β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β Bash loop checks for DONE β β
β β If found: next iteration | If not: retry β β
β ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
```
### The Magic Phrase
The agent outputs `DONE` **ONLY** when:
- All acceptance criteria are verified
- Tests pass
- Changes are committed and pushed
The shell or PowerShell loop checks for this phrase. If not found, it retries.
---
## Two Modes
| Mode | Purpose | Command |
|------|---------|---------|
| **build** (default) | Pick spec/task, implement, test, commit | `./scripts/ralph-loop.sh` |
| **plan** (optional) | Create detailed task breakdown from specs | `./scripts/ralph-loop.sh plan` |
On Windows PowerShell, use the matching `.ps1` scripts, for example
`.\scripts\ralph-loop.ps1` or `.\scripts\ralph-loop-codex.ps1 plan`.
### Planning is OPTIONAL
Most projects work fine **directly from specs**. The agent simply:
1. Looks at `specs/` folder
2. Picks the highest priority incomplete spec
3. Implements it completely
Only use `plan` mode when you want a detailed breakdown of specs into smaller tasks.
**Tip:** Delete `IMPLEMENTATION_PLAN.md` to return to working directly from specs.
---
## Installation
### For AI Agents (Recommended)
Point your AI agent to this repo and say:
> "Set up Ralph Wiggum in my project using https://github.com/fstandhartinger/ralph-wiggum"
The agent will read [INSTALLATION.md](INSTALLATION.md) and guide you through a **lightweight, pleasant setup**:
1. **Quick Setup** (~1 min) β Create directories, download scripts
2. **Project Interview** (~3-5 min) β Focus on your **vision and goals**, not technical minutiae
3. **Constitution** β Create a guiding document for all future sessions
4. **Next Steps** β Clear guidance on creating specs and starting Ralph
The interview prioritizes understanding *what you're building and why* over interrogating you about tech stack details. For existing projects, the agent can detect your stack automatically.
### Manual Setup
See [INSTALL.md](INSTALL.md) for step-by-step manual instructions.
---
## Usage
### 1. Create Specifications
Tell your AI what you want to build, or use `/speckit.specify` in Cursor:
```
/speckit.specify Add user authentication with OAuth
```
This creates `specs/001-user-auth/spec.md` with:
- Feature requirements
- **Clear, testable acceptance criteria** (critical!)
- Completion signal section
**The key to good specs:** Each spec needs acceptance criteria that are **specific and testable**. Not "works correctly" but "user can log in with Google and session persists across page reloads."
### 2. (Optional) Run Planning Mode
```bash
./scripts/ralph-loop.sh plan
```
Creates `IMPLEMENTATION_PLAN.md` with detailed task breakdown. **This step is optional** β most projects work fine directly from specs.
### 3. Run Build Mode
```bash
./scripts/ralph-loop.sh # Unlimited iterations
./scripts/ralph-loop.sh 20 # Max 20 iterations
```
Each iteration:
1. Picks the highest priority task
2. Implements it completely
3. Verifies acceptance criteria
4. Outputs `DONE` only if criteria pass
5. Bash loop checks for the phrase
6. Context cleared, next iteration starts
### Logging (All Output Captured)
Every loop run writes **all output** to log files in `logs/`:
- **Session log:** `logs/ralph_*_session_YYYYMMDD_HHMMSS.log` (entire run, including CLI output)
- **Iteration logs:** `logs/ralph_*_iter_N_YYYYMMDD_HHMMSS.log` (per-iteration CLI output)
- **Codex last message:** `logs/ralph_codex_output_iter_N_*.txt`
If something gets stuck, these logs contain the full verbose trace.
### NR_OF_TRIES Tracking
Each spec tracks how many times it has been attempted. After 10 attempts without completion, the spec is flagged as "stuck" and should be split into smaller specs.
```bash
# Check stuck specs
source scripts/lib/nr_of_tries.sh
print_stuck_specs_summary
```
The counter is stored as a comment in the spec file:
```markdown
```
### Telegram Notifications (Optional)
Get progress updates via Telegram! See [TELEGRAM_SETUP.md](TELEGRAM_SETUP.md) for setup.
```bash
# Enable telegram (requires TG_BOT_TOKEN and TG_CHAT_ID)
./scripts/ralph-loop.sh
# Enable audio notifications (also requires CHUTES_API_KEY)
./scripts/ralph-loop.sh --telegram-audio
# Disable telegram
./scripts/ralph-loop.sh --no-telegram
```
**What you'll get:**
- π Loop start notifications
- β
Spec completion notifications with mermaid diagrams
- β οΈ Warnings for consecutive failures or stuck specs
- π Summary when loop finishes
### Completion Logs
On each spec completion, entries are created in `completion_log/`:
- `YYYY-MM-DD--HH-MM-SS--spec-name.md` β Summary and mermaid code
- `YYYY-MM-DD--HH-MM-SS--spec-name.png` β Rendered mermaid diagram
These provide a visual history of what was built.
### Using Codex Instead
```bash
./scripts/ralph-loop-codex.sh plan
./scripts/ralph-loop-codex.sh
```
PowerShell:
```powershell
.\scripts\ralph-loop-codex.ps1 plan
.\scripts\ralph-loop-codex.ps1
```
---
## File Structure
```
project/
βββ .specify/
β βββ memory/
β βββ constitution.md # Single source of truth for all agent behavior
βββ specs/
β βββ NNN-feature-name.md # Feature specifications
βββ scripts/
β βββ ralph-loop.sh # Claude Code loop
β βββ ralph-loop.ps1 # Claude Code loop for PowerShell
β βββ ralph-loop-codex.sh # OpenAI Codex loop
β βββ ralph-loop-codex.ps1 # OpenAI Codex loop for PowerShell
β βββ ralph-loop-gemini.sh # Google Gemini loop
β βββ ralph-loop-gemini.ps1 # Google Gemini loop for PowerShell
β βββ ralph-loop-copilot.sh # GitHub Copilot loop
β βββ ralph-loop-copilot.ps1 # GitHub Copilot loop for PowerShell
β βββ lib/ # Shared shell and PowerShell helpers
βββ AGENTS.md # Points to constitution
βββ CLAUDE.md # Points to constitution
```
The **constitution** is the single source of truth. Optional features (Telegram, GitHub Issues, completion logs) are configured there β not baked into the scripts.
---
## Core Principles
### 1. Fresh Context Each Loop
Each iteration gets a clean context window. The agent reads files from disk each time.
### 2. Shared State on Disk
`IMPLEMENTATION_PLAN.md` persists between loops. Agent reads it to pick tasks, updates it with progress.
### 3. Backpressure via Tests
Tests, lints, and builds reject invalid work. Agent must fix issues before the magic phrase.
### 4. Completion Verification
Agent only outputs `DONE` when acceptance criteria are 100% verified. The bash loop enforces this.
### 5. Let Ralph Ralph
Trust the AI to self-identify, self-correct, and self-improve. Observe patterns and adjust prompts.
---
## Alternative Spec Sources
During installation, you can choose:
1. **SpecKit Specs** (default) β Markdown files in `specs/`
2. **GitHub Issues** β Fetch from a repository
3. **Custom Source** β Your own mechanism
The constitution and prompts adapt accordingly.
---
## Agent Skills Compatibility
Ralph Wiggum follows the [Agent Skills specification](https://agentskills.io) and is compatible with:
| Installer | Command |
|-----------|---------|
| [Vercel add-skill](https://github.com/vercel-labs/add-skill) | `npx add-skill fstandhartinger/ralph-wiggum` |
| [OpenSkills](https://github.com/numman-ali/openskills) | `openskills install fstandhartinger/ralph-wiggum` |
| [Skillset](https://github.com/climax-tools/skillset) | `skillset add fstandhartinger/ralph-wiggum` |
Works with: **Claude Code**, **Cursor**, **Codex**, **Windsurf**, **Amp**, **OpenCode**, and more.
---
## Credits
This approach builds upon:
- [Geoffrey Huntley's how-to-ralph-wiggum](https://github.com/ghuntley/how-to-ralph-wiggum) β The original methodology
- [Original Ralph Wiggum technique](https://awesomeclaude.ai/ralph-wiggum) β By the Claude community
- [Claude Code Ralph Wiggum plugin](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum)
- [SpecKit](https://github.com/github/spec-kit) by GitHub β Spec-driven development
Our contribution: Combining the bash loop approach with SpecKit-style specifications and a smooth AI-driven installation process.
---
## License
MIT License β See [LICENSE](LICENSE) for details.
---
**Website**: [ralph-wiggum-web.onrender.com](https://ralph-wiggum-web.onrender.com)