Ralph Wiggum skill
An autonomous spec-driven coding loop: the agent takes a task, checks acceptance criteria and commits until the list runs out.
- 311 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The autonomous loop changes code, commits and pushes on every iteration without separate confirmation.
- The agent gets significant autonomy over the project and system, so running without isolation endangers the rest of the code.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/ralph-wiggumDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The autonomous loop changes code, commits and pushes on every iteration without separate confirmation.
- The agent gets significant autonomy over the project and system, so running without isolation endangers the rest of the code.
This is third-party code. Review the repository files before installing.
What it does
Ralph Wiggum runs an AI agent in a loop: each iteration picks one spec from `specs/`, implements it, checks acceptance criteria and commits the result. The method builds on Geoffrey Huntley's iterative bash loop and adds SpecKit-style specifications. The script looks for a `<promise>DONE</promise>` marker in the reply. The agent prints it only after all criteria are met and tests pass, and without the marker the iteration repeats. Every pass starts with a clean context, while state lives on disk: an `IMPLEMENTATION_PLAN.md` file, an attempt counter in a spec comment and logs in `logs/`. Scripts exist for Claude Code, Codex, Gemini and Copilot, in bash and PowerShell variants. The agent drives the setup from `INSTALLATION.md`: a short project interview and a project constitution with rules for future sessions.
Who it is for. Developers ready to hand an agent a queue of specs and review the outcome through tests and logs.
Good fit when
- You have a set of specs with checkable acceptance criteria and want them implemented in a row without launching the agent by hand.
- A long session overflows the context, and each task is better started in a clean window.
- A spec got stuck after ten attempts and should be split into parts.
- You want progress in Telegram: loop start, finished specs, warnings.
- The same loop runs in Codex, Gemini or Copilot instead of Claude Code.
Not a fit when
- There are no specs and the acceptance criteria are vague: the loop cannot tell finished work from unfinished.
- The repository holds important code and there is no isolation: the tool gets significant autonomy over code and system.
- Pushes without your review are unacceptable: an iteration ends with a commit and a push.
- You need a one-off small edit: setting up a constitution and a loop for it is excessive.
Example request
Set up Ralph Wiggum in my project using https://github.com/fstandhartinger/ralph-wiggum and explain how to write specs.Limitations
The repository warns that the tool gives an agent significant autonomy over code and system: it advises running it in an isolated environment and reviewing every change. Result quality rests on acceptance criteria in the specs and on tests, and vague criteria lead to repeated fruitless iterations. Optional Telegram notifications need `TG_BOT_TOKEN` and `TG_CHAT_ID`, and audio ones also need `CHUTES_API_KEY`. The last commit dates from May 2026.
How to disable. Stop a running loop by interrupting the process. Delete the `ralph-wiggum` skill from the agent's skills directory and, after a full setup, the `scripts/ralph-loop*` scripts plus the project's `specs/` and `.specify/` directories.
FAQ
How do I install Ralph Wiggum as a skill?
Run `npx add-skill fstandhartinger/ralph-wiggum` or `openskills install fstandhartinger/ralph-wiggum`. For a full setup, ask the agent to execute `INSTALLATION.md`.
How do I start the loop?
Put specs in `specs/` and run `./scripts/ralph-loop.sh`. A number after the command caps iterations, for example `./scripts/ralph-loop.sh 20`. The `plan` mode builds `IMPLEMENTATION_PLAN.md` and is optional.
How does the loop know a task is done?
The agent prints `<promise>DONE</promise>` only after checking every acceptance criterion, passing tests, committing and pushing. Without the marker the script repeats the iteration.
What if a spec keeps failing?
After ten attempts it counts as stuck. The counter lives in the comment `<!-- NR_OF_TRIES: 5 -->`, and `print_stuck_specs_summary` prints the overview. Split such a spec into smaller ones.
Can I run the loop in Codex?
Yes: `./scripts/ralph-loop-codex.sh`, with the `plan` parameter for planning. Gemini and Copilot variants exist, and `.ps1` files cover Windows.
Discussion
No questions or reviews yet.
Related
SkillsThe ralph command repeats one prompt for Claude Code, Codex, Cursor Agent or OpenCode until a completion tag appears in the reply
A Ralph loop for long tasks: an agent in a Docker sandbox works through a PRD task list, checks each task with tests and commits until the list is done
A CLI orchestrator that loops Claude Code, Codex, Gemini CLI and other agents until a task is done and blocks incomplete work with tests and lint
A terminal dashboard that drives Claude Code, Codex and five more agents through a task list in a loop until the list is done
A Claude Code skill and /looper command that interviews you and builds an agent loop with checks, an independent reviewer and stop rules before it runs
Autonomous plan execution task by task: each task in a fresh Claude Code or Codex session, then a multi-pass review. Written in Go
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| Ralph Wiggum (this card) | no | 311 | |
| Open Ralph Wiggum | no | 1,908 | a ralph command that repeats one prompt until a completion marker appears; here the loop works through specs with acceptance criteria and an attempt counter |
| Ralph Loop by PageAI | no | 337 | a loop in a Docker sandbox over a PRD task list; here SpecKit-style specs and a setup run by the agent itself |
README in short
The document lays out Huntley's method with SpecKit specs added and two modes: build and optional planning. The principles are stated outright: clean context each pass, state on disk, tests as feedback and completion checks. It then covers spec sources (files, GitHub issues, a custom mechanism) and compatibility with skill installers.
README badge
Original SKILL.md
--- 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 --- # Ralph Wiggum > Autonomous AI coding with spec-driven development ## What is Ralph Wiggum? 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. ## When to Use This Skill Use Ralph Wiggum when: - You have multiple specifications/features to implement - You want the AI to work autonomously through tasks - You need consistent, verifiable completion of acceptance criteria - You want to avoid context window problems in long sessions ## How It Works ``` ┌─────────────────────────────────────────────────────────────┐ │ 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) │ └─────────────────────────────────────────────────────────────┘ ``` ## Installation ### Quick Install (via Skill Installers)