Skip to content
/ ralph-wiggum Public

Ralph Wiggum: Autonomous AI coding with spec-driven development. Point your AI agent here to get started.

License

MIT license
183 stars 14 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

fstandhartinger/ralph-wiggum

BranchesTags

Repository files navigation

🧠 Ralph Wiggum

Autonomous AI coding with spec-driven development

License: MIT

⚠️ 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!)

# 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 for a guided setup with interactive interview.

Human Developer? Start Here:

Read 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 <promise>DONE</promise> 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:

┌─────────────────────────────────────────────────────────────┐
│                     RALPH LOOP                              │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │    Orient    │───▶│  Pick Task   │───▶│  Implement   │  │
│  │  Read specs  │    │  from Plan   │    │   & Test     │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
│                                                   │         │
│         ┌────────────────────────────────────────┘         │
│         ▼                                                   │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐  │
│  │   Verify     │───▶│   Commit     │───▶│  Output DONE │  │
│  │  Criteria    │    │   & Push     │    │  (if passed) │  │
│  └──────────────┘    └──────────────┘    └──────────────┘  │
│                                                   │         │
│         ┌────────────────────────────────────────┘         │
│         ▼                                                   │
│  ┌──────────────────────────────────────────────────────┐  │
│  │ Bash loop checks for <promise>DONE</promise>         │  │
│  │ If found: next iteration | If not: retry             │  │
│  └──────────────────────────────────────────────────────┘  │
│                                                             │
└─────────────────────────────────────────────────────────────┘

The Magic Phrase

The agent outputs <promise>DONE</promise> ONLY when:

  • All acceptance criteria are verified
  • Tests pass
  • Changes are committed and pushed

The bash 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

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

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

./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 <promise>DONE</promise> 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.

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

<!-- NR_OF_TRIES: 5 -->

Telegram Notifications (Optional)

Get progress updates via Telegram! See TELEGRAM_SETUP.md for setup.

# 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

./scripts/ralph-loop-codex.sh plan
./scripts/ralph-loop-codex.sh

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-codex.sh       # OpenAI Codex loop
│   ├── ralph-loop-gemini.sh      # Google Gemini loop
│   └── ralph-loop-copilot.sh     # GitHub Copilot loop
├── 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 <promise>DONE</promise> 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 and is compatible with:

Installer Command
Vercel add-skill npx add-skill fstandhartinger/ralph-wiggum
OpenSkills openskills install fstandhartinger/ralph-wiggum
Skillset skillset add fstandhartinger/ralph-wiggum

Works with: Claude Code, Cursor, Codex, Windsurf, Amp, OpenCode, and more.

Credits

This approach builds upon:

Our contribution: Combining the bash loop approach with SpecKit-style specifications and a smooth AI-driven installation process.

License

MIT License — See LICENSE for details.

Website: ralph-wiggum-web.onrender.com

About

Ralph Wiggum: Autonomous AI coding with spec-driven development. Point your AI agent here to get started.

Resources

Readme

License

MIT license
Activity

Stars

183 stars

Watchers

0 watching

Forks

14 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages