// Autonomous AI coding with spec-driven development. Implements Geoffrey Huntley's iterative bash loop methodology where agents work through specs one at a time, outputting a completion signal only when acceptance criteria are 100% met.
| name | ralph-wiggum |
| description | Autonomous AI coding with spec-driven development. Implements Geoffrey Huntley's iterative bash loop methodology where agents work through specs one at a time, outputting a completion signal only when acceptance criteria are 100% met. |
| license | MIT |
| metadata | {"author":"fstandhartinger","version":"1.0","repository":"https://github.com/fstandhartinger/ralph-wiggum","website":"https://ralph-wiggum.ai"} |
Autonomous AI coding with spec-driven development
Ralph Wiggum combines Geoffrey Huntley's iterative bash loop with spec-driven development for fully autonomous AI-assisted software development.
The key insight: Fresh context each iteration. Each loop starts a new agent process with a clean context window, preventing context overflow and degradation.
Use Ralph Wiggum when:
┌─────────────────────────────────────────────────────────────┐
│ RALPH LOOP │
├─────────────────────────────────────────────────────────────┤
│ Loop 1: Pick spec A → Implement → Test → Commit → DONE │
│ Loop 2: Pick spec B → Implement → Test → Commit → DONE │
│ Loop 3: Pick spec C → Implement → Test → Commit → DONE │
│ ... │
│ │
│ Each iteration = Fresh context window │
│ Shared state = Files on disk (specs, plan, history) │
└─────────────────────────────────────────────────────────────┘
# Using Vercel's add-skill
npx add-skill fstandhartinger/ralph-wiggum
# Using OpenSkills
openskills install fstandhartinger/ralph-wiggum
For full Ralph Wiggum setup with constitution and interview:
# Tell your AI agent:
"Set up Ralph Wiggum using https://github.com/fstandhartinger/ralph-wiggum"
The agent will guide you through a lightweight, pleasant setup:
For existing projects, the agent detects your tech stack automatically. The interview prioritizes understanding what you're building and why.
Each iteration of the Ralph loop starts a new AI agent process. This means:
State persists between loops via files:
specs/ — Feature specifications with acceptance criteriaralph_history.txt — Log of breakthroughs, blockers, learningsIMPLEMENTATION_PLAN.md — Optional detailed task breakdownThe agent outputs <promise>DONE</promise> ONLY when:
The bash loop checks for this phrase. If not found, it retries.
Tests, lints, and builds act as guardrails. The agent must fix issues before outputting the completion signal.
The key to success: Each spec needs clear, testable acceptance criteria. This is what tells Ralph when a task is truly "done."
# Feature: User Authentication
## Requirements
- OAuth login with Google
- Session management
- Logout functionality
## Acceptance Criteria
- [ ] User can log in with Google
- [ ] Session persists across page reloads
- [ ] User can log out
- [ ] Tests pass
**Output when complete:** `<promise>DONE</promise>`
Good criteria: "User can log in with Google and session persists" Bad criteria: "Auth works correctly"
The more specific your acceptance criteria, the better Ralph performs.
# Start building (Claude Code)
./scripts/ralph-loop.sh
# With max iterations
./scripts/ralph-loop.sh 20
# Using Codex CLI
./scripts/ralph-loop-codex.sh
Every loop run writes all output to log files in logs/:
logs/ralph_*_session_YYYYMMDD_HHMMSS.log (entire run, including CLI output)logs/ralph_*_iter_N_YYYYMMDD_HHMMSS.log (per-iteration CLI output)logs/ralph_codex_output_iter_N_*.txt| Mode | Purpose | Command |
|---|---|---|
| build (default) | Pick spec, implement, test, commit | ./scripts/ralph-loop.sh |
| plan (optional) | Create detailed task breakdown | ./scripts/ralph-loop.sh plan |
Trust the AI to self-identify, self-correct, and self-improve. Observe patterns and adjust prompts.
For Ralph to work effectively, enable full autonomy:
--dangerously-skip-permissions--dangerously-bypass-approvals-and-sandbox⚠️ Use at your own risk. Only in sandboxed environments.