Skip to content
Back to search

ralph-wiggum

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fstandhartinger-ralph-wiggum/badge.svg)](/listings/fstandhartinger-ralph-wiggum)

HTML

<a href="/listings/fstandhartinger-ralph-wiggum"><img src="/api/listings/fstandhartinger-ralph-wiggum/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](INSTALLATION.md) for a guided setup with interactive interview.

**Human Developer? Start Here:** > Read [INSTALL.md](INSTALL.md) for manual setup instructions.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 334 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # 🧠 Ralph Wiggum
  2. > Autonomous AI coding with spec-driven development
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  4. ⚠️ **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.
  5. ## Quick Start
  6. ### Install as Agent Skill (New!)
  7. ```bash
  8. # Using Vercel's add-skill
  9. npx add-skill fstandhartinger/ralph-wiggum
  10. # Using OpenSkills
  11. openskills install fstandhartinger/ralph-wiggum
  12. ```
  13. ### Full Setup with Interview
  14. **AI Agent? Start Here:**
  15. > Read and execute [INSTALLATION.md](INSTALLATION.md) for a guided setup with interactive interview.
  16. **Human Developer? Start Here:**
  17. > Read [INSTALL.md](INSTALL.md) for manual setup instructions.
  18. ---
  19. ## What is Ralph Wiggum?
  20. Ralph Wiggum (in this flavour) combines **Geoffrey Huntley's original iterative bash loop** with **SpecKit-style specifications** for fully autonomous AI-assisted software development.
  21. ### Key Features
  22. - 🔄 **Iterative Self-Correction** — Each loop picks ONE task, implements it, verifies, and commits
  23. - 📋 **Spec-Driven Development** — Professional specifications with clear acceptance criteria
  24. - 🎯 **Completion Verification** — Agent only outputs `<promise>DONE</promise>` when criteria are 100% met
  25. - 🧠 **Fresh Context Each Loop** — Every iteration starts with a clean context window
  26. - 📝 **Shared State on Disk** — `IMPLEMENTATION_PLAN.md` persists between loops
  27. ---
  28. ## How It Works
  29. Based on [Geoffrey Huntley's methodology](https://github.com/ghuntley/how-to-ralph-wiggum):
  30. ```
  31. ┌─────────────────────────────────────────────────────────────┐
  32. │ RALPH LOOP │
  33. ├─────────────────────────────────────────────────────────────┤
  34. │ │
  35. │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
  36. │ │ Orient │───▶│ Pick Task │───▶│ Implement │ │
  37. │ │ Read specs │ │ from Plan │ │ & Test │ │
  38. │ └──────────────┘ └──────────────┘ └──────────────┘ │
  39. │ │ │
  40. │ ┌────────────────────────────────────────┘ │
  41. │ ▼ │
  42. │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
  43. │ │ Verify │───▶│ Commit │───▶│ Output DONE │ │
  44. │ │ Criteria │ │ & Push │ │ (if passed) │ │
  45. │ └──────────────┘ └──────────────┘ └──────────────┘ │
  46. │ │ │
  47. │ ┌────────────────────────────────────────┘ │
  48. │ ▼ │
  49. │ ┌──────────────────────────────────────────────────────┐ │
  50. │ │ Bash loop checks for <promise>DONE</promise> │ │
  51. │ │ If found: next iteration | If not: retry │ │
  52. │ └──────────────────────────────────────────────────────┘ │
  53. │ │
  54. └─────────────────────────────────────────────────────────────┘
  55. ```
  56. ### The Magic Phrase
  57. The agent outputs `<promise>DONE</promise>` **ONLY** when:
  58. - All acceptance criteria are verified
  59. - Tests pass
  60. - Changes are committed and pushed
  61. The shell or PowerShell loop checks for this phrase. If not found, it retries.
  62. ---
  63. ## Two Modes
  64. | Mode | Purpose | Command |
  65. |------|---------|---------|
  66. | **build** (default) | Pick spec/task, implement, test, commit | `./scripts/ralph-loop.sh` |
  67. | **plan** (optional) | Create detailed task breakdown from specs | `./scripts/ralph-loop.sh plan` |
  68. On Windows PowerShell, use the matching `.ps1` scripts, for example
  69. `.\scripts\ralph-loop.ps1` or `.\scripts\ralph-loop-codex.ps1 plan`.
  70. ### Planning is OPTIONAL
  71. Most projects work fine **directly from specs**. The agent simply:
  72. 1. Looks at `specs/` folder
  73. 2. Picks the highest priority incomplete spec
  74. 3. Implements it completely
  75. Only use `plan` mode when you want a detailed breakdown of specs into smaller tasks.
  76. **Tip:** Delete `IMPLEMENTATION_PLAN.md` to return to working directly from specs.
  77. ---
  78. ## Installation
  79. ### For AI Agents (Recommended)
  80. Point your AI agent to this repo and say:
  81. > "Set up Ralph Wiggum in my project using https://github.com/fstandhartinger/ralph-wiggum"
  82. The agent will read [INSTALLATION.md](INSTALLATION.md) and guide you through a **lightweight, pleasant setup**:
  83. 1. **Quick Setup** (~1 min) — Create directories, download scripts
  84. 2. **Project Interview** (~3-5 min) — Focus on your **vision and goals**, not technical minutiae
  85. 3. **Constitution** — Create a guiding document for all future sessions
  86. 4. **Next Steps** — Clear guidance on creating specs and starting Ralph
  87. 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.
  88. ### Manual Setup
  89. See [INSTALL.md](INSTALL.md) for step-by-step manual instructions.
  90. ---
  91. ## Usage
  92. ### 1. Create Specifications
  93. Tell your AI what you want to build, or use `/speckit.specify` in Cursor:
  94. ```
  95. /speckit.specify Add user authentication with OAuth
  96. ```
  97. This creates `specs/001-user-auth/spec.md` with:
  98. - Feature requirements
  99. - **Clear, testable acceptance criteria** (critical!)
  100. - Completion signal section
  101. **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."
  102. ### 2. (Optional) Run Planning Mode
  103. ```bash
  104. ./scripts/ralph-loop.sh plan
  105. ```
  106. Creates `IMPLEMENTATION_PLAN.md` with detailed task breakdown. **This step is optional** — most projects work fine directly from specs.
  107. ### 3. Run Build Mode
  108. ```bash
  109. ./scripts/ralph-loop.sh # Unlimited iterations
  110. ./scripts/ralph-loop.sh 20 # Max 20 iterations
  111. ```
  112. Each iteration:
  113. 1. Picks the highest priority task
  114. 2. Implements it completely
  115. 3. Verifies acceptance criteria
  116. 4. Outputs `<promise>DONE</promise>` only if criteria pass
  117. 5. Bash loop checks for the phrase
  118. 6. Context cleared, next iteration starts
  119. ### Logging (All Output Captured)
  120. Every loop run writes **all output** to log files in `logs/`:
  121. - **Session log:** `logs/ralph_*_session_YYYYMMDD_HHMMSS.log` (entire run, including CLI output)
  122. - **Iteration logs:** `logs/ralph_*_iter_N_YYYYMMDD_HHMMSS.log` (per-iteration CLI output)
  123. - **Codex last message:** `logs/ralph_codex_output_iter_N_*.txt`
  124. If something gets stuck, these logs contain the full verbose trace.
  125. ### NR_OF_TRIES Tracking
  126. 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.
  127. ```bash
  128. # Check stuck specs
  129. source scripts/lib/nr_of_tries.sh
  130. print_stuck_specs_summary
  131. ```
  132. The counter is stored as a comment in the spec file:
  133. ```markdown
  134. <!-- NR_OF_TRIES: 5 -->
  135. ```
  136. ### Telegram Notifications (Optional)
  137. Get progress updates via Telegram! See [TELEGRAM_SETUP.md](TELEGRAM_SETUP.md) for setup.
  138. ```bash
  139. # Enable telegram (requires TG_BOT_TOKEN and TG_CHAT_ID)
  140. ./scripts/ralph-loop.sh
  141. # Enable audio notifications (also requires CHUTES_API_KEY)
  142. ./scripts/ralph-loop.sh --telegram-audio
  143. # Disable telegram
  144. ./scripts/ralph-loop.sh --no-telegram
  145. ```
  146. **What you'll get:**
  147. - 🚀 Loop start notifications
  148. - ✅ Spec completion notifications with mermaid diagrams
  149. - ⚠️ Warnings for consecutive failures or stuck specs
  150. - 🏁 Summary when loop finishes
  151. ### Completion Logs
  152. On each spec completion, entries are created in `completion_log/`:
  153. - `YYYY-MM-DD--HH-MM-SS--spec-name.md` — Summary and mermaid code
  154. - `YYYY-MM-DD--HH-MM-SS--spec-name.png` — Rendered mermaid diagram
  155. These provide a visual history of what was built.
  156. ### Using Codex Instead
  157. ```bash
  158. ./scripts/ralph-loop-codex.sh plan
  159. ./scripts/ralph-loop-codex.sh
  160. ```
  161. PowerShell:
  162. ```powershell
  163. .\scripts\ralph-loop-codex.ps1 plan
  164. .\scripts\ralph-loop-codex.ps1
  165. ```
  166. ---
  167. ## File Structure
  168. ```
  169. project/
  170. ├── .specify/
  171. │ └── memory/
  172. │ └── constitution.md # Single source of truth for all agent behavior
  173. ├── specs/
  174. │ └── NNN-feature-name.md # Feature specifications
  175. ├── scripts/
  176. │ ├── ralph-loop.sh # Claude Code loop
  177. │ ├── ralph-loop.ps1 # Claude Code loop for PowerShell
  178. │ ├── ralph-loop-codex.sh # OpenAI Codex loop
  179. │ ├── ralph-loop-codex.ps1 # OpenAI Codex loop for PowerShell
  180. │ ├── ralph-loop-gemini.sh # Google Gemini loop
  181. │ ├── ralph-loop-gemini.ps1 # Google Gemini loop for PowerShell
  182. │ ├── ralph-loop-copilot.sh # GitHub Copilot loop
  183. │ ├── ralph-loop-copilot.ps1 # GitHub Copilot loop for PowerShell
  184. │ └── lib/ # Shared shell and PowerShell helpers
  185. ├── AGENTS.md # Points to constitution
  186. └── CLAUDE.md # Points to constitution
  187. ```
  188. The **constitution** is the single source of truth. Optional features (Telegram, GitHub Issues, completion logs) are configured there — not baked into the scripts.
  189. ---
  190. ## Core Principles
  191. ### 1. Fresh Context Each Loop
  192. Each iteration gets a clean context window. The agent reads files from disk each time.
  193. ### 2. Shared State on Disk
  194. `IMPLEMENTATION_PLAN.md` persists between loops. Agent reads it to pick tasks, updates it with progress.
  195. ### 3. Backpressure via Tests
  196. Tests, lints, and builds reject invalid work. Agent must fix issues before the magic phrase.
  197. ### 4. Completion Verification
  198. Agent only outputs `<promise>DONE</promise>` when acceptance criteria are 100% verified. The bash loop enforces this.
  199. ### 5. Let Ralph Ralph
  200. Trust the AI to self-identify, self-correct, and self-improve. Observe patterns and adjust prompts.
  201. ---
  202. ## Alternative Spec Sources
  203. During installation, you can choose:
  204. 1. **SpecKit Specs** (default) — Markdown files in `specs/`
  205. 2. **GitHub Issues** — Fetch from a repository
  206. 3. **Custom Source** — Your own mechanism
  207. The constitution and prompts adapt accordingly.
  208. ---
  209. ## Agent Skills Compatibility
  210. Ralph Wiggum follows the [Agent Skills specification](https://agentskills.io) and is compatible with:
  211. | Installer | Command |
  212. |-----------|---------|
  213. | [Vercel add-skill](https://github.com/vercel-labs/add-skill) | `npx add-skill fstandhartinger/ralph-wiggum` |
  214. | [OpenSkills](https://github.com/numman-ali/openskills) | `openskills install fstandhartinger/ralph-wiggum` |
  215. | [Skillset](https://github.com/climax-tools/skillset) | `skillset add fstandhartinger/ralph-wiggum` |
  216. Works with: **Claude Code**, **Cursor**, **Codex**, **Windsurf**, **Amp**, **OpenCode**, and more.
  217. ---
  218. ## Credits
  219. This approach builds upon:
  220. - [Geoffrey Huntley's how-to-ralph-wiggum](https://github.com/ghuntley/how-to-ralph-wiggum) — The original methodology
  221. - [Original Ralph Wiggum technique](https://awesomeclaude.ai/ralph-wiggum) — By the Claude community
  222. - [Claude Code Ralph Wiggum plugin](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum)
  223. - [SpecKit](https://github.com/github/spec-kit) by GitHub — Spec-driven development
  224. Our contribution: Combining the bash loop approach with SpecKit-style specifications and a smooth AI-driven installation process.
  225. ---
  226. ## License
  227. MIT License — See [LICENSE](LICENSE) for details.
  228. ---
  229. **Website**: [ralph-wiggum-web.onrender.com](https://ralph-wiggum-web.onrender.com)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.