setup-ralph — Claude Code skill: Ralph loop setup and install
setup-ralph lays out Geoffrey Huntley's Ralph Wiggum loop in a directory: file structure, planning and build prompts, and gates that reject bad work.
MIT ★ 1,988 updated 2026-04-01
/plugin marketplace add glittercowboy/taches-cc-resources
/plugin install taches-cc-resources@taches-cc-resourcesWhat setup-ralph does
The skill builds the loop around while :; do cat PROMPT.md | claude ; done. One pass takes a single task off the plan, finishes it, commits, exits. Then the cycle restarts with empty context. Work splits into planning (compare specs against code, write a task list), building, and sitting outside the loop to watch it run.
On start it asks what you need: a fresh loop, an explanation of the method, prompt edits, or debugging. It then opens the matching file under workflows/ and follows it. Background material in references/ covers project layout, prompt design, a validation strategy, and notes from operating loops.
Rejection of poor output comes from tests, typechecks, lints and builds. The automatic backup to a private GitHub repo needs an authenticated gh CLI; skip that and you disable it with RALPH_BACKUP=false. PROMPT_build.md forbids dangerous commands such as rm -rf against project folders, and tests belong in isolated temp directories.
What it helps with
- spin up the Ralph folder structure in a new directory
- turn spec-versus-code gaps into a ranked task list
- wire tests, lints and builds into a rejection gate
- rewrite planning and build prompts for your own repo
- diagnose a loop that stalls and adjust its configuration
Example prompts for the agent
- Set up a new Ralph loop in this repo with setup-ralph.
- Walk me through the Ralph method and what each phase is for.
- Tune the prompts in my existing loop; the planning output is too vague.
How to install setup-ralph
1Plugin marketplace
/plugin marketplace add glittercowboy/taches-cc-resources/plugin install taches-cc-resources@taches-cc-resourcesThis installs the whole taches-cc-resources plugin with all its skills
2Skills CLI (Vercel)
npx skills add glittercowboy/taches-cc-resources --skill setup-ralph -a claude-code3Manually: put the files in place
~/.claude/skills/setup-ralph/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/setup-ralph/
1Skills CLI (Vercel)
npx skills add glittercowboy/taches-cc-resources --skill setup-ralph -a codex2Manually: put the files in place
.agents/skills/setup-ralph/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add glittercowboy/taches-cc-resources --skill setup-ralph -a cursor2Manually: put the files in place
.cursor/skills/setup-ralph/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install glittercowboy/taches-cc-resources skills/setup-ralph2Manually: put the files in place
.github/skills/setup-ralph/SKILL.md1Skills CLI (Vercel)
npx skills add glittercowboy/taches-cc-resources --skill setup-ralph -a gemini-cli2Platform CLI
gemini skills install https://github.com/glittercowboy/taches-cc-resources --path skills/setup-ralphManually: put the files in place
.devin/skills/setup-ralph/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about setup-ralph
How do I install setup-ralph in Claude Code?
From the marketplace: run /plugin marketplace add glittercowboy/taches-cc-resources, then /plugin install taches-cc-resources@taches-cc-resources.
What does setup-ralph do?
It sets up the Ralph Wiggum loop in a directory: file layout, planning and build prompts, and the validation rules. It also handles concept walkthroughs, prompt customisation and debugging.
Why does the loop want an authenticated gh CLI?
Each commit gets pushed to a private GitHub repo so autonomous runs cannot wipe your work. Set RALPH_BACKUP=false if you do not want that copy.
Source text
SKILL.md · MIT
--- name: setup-ralph description: Set up and configure Geoffrey Huntley's original Ralph Wiggum autonomous coding loop in any directory with proper structure, prompts, and backpressure. --- <essential_principles> ## What is Ralph? Ralph is Geoffrey Huntley's autonomous AI coding methodology that uses iterative loops with task selection, execution, and validation. In its purest form, it's a Bash loop: ```bash while :; do cat PROMPT.md | claude ; done ``` The loop feeds a prompt file to Claude, the agent completes one task, updates the implementation plan, commits changes, then exits. The loop restarts immediately with fresh context. ### Core Philosophy **The Ralph Wiggum Technique is deterministically bad in an undeterministic world.** Ralph solves context accumulation by starting each iteration with fresh context—the core insight behind Geoffrey's approach. ### Three Phases, Two Prompts, One Loop 1. **Planning Phase**: Gap analysis (specs vs code) outputs prioritized TODO list—no implementation, no commits 2. **Building Phase**: Picks tasks from plan, implements, runs tests (backpressure), commits 3. **Observation Phase**: You sit on the loop, not in it—engineer the setup and environment that allows Ralph to succeed ### Key Principles **Your Role**: Ralph does all the work, including deciding which planned work to implement next and how to implement it. Your job is to engineer the environment. **Backpressure**: Create backpressure via tests, typechecks, lints, builds that reject invalid/unacceptable work. **Observation**: Watch, especially early on. Prompts evolve through observed failure patterns. **Context Efficiency**: With ~176K usable tokens from 200K window, allocating 40-60% to "smart zone" means tight tasks with one task per loop achieves maximum context utilization. **File I/O as State**: The plan file persists between isolated loop executions, serving as deterministic shared state—no sophisticated orchestration needed. **Remote Backup**: The loop automatically creates a private GitHub repo and pushes after each commit. This protects against accidental data loss from autonomous operations. Requires `gh` CLI authenticated. Disable with `RALPH_BACKUP=false`. **Safety Rules**: PROMPT_build.md includes critical safety rules prohibiting dangerous operations like `rm -rf` on project directories. Tests must run in isolated temp directories. </essential_principles> <intake> What would you like to do? 1. **Set up a new Ralph loop** - Initialize Ralph structure in a directory 2. **Understand Ralph concepts** - Learn about the technique and how it works 3. **Customize existing loop** - Modify prompts or configuration 4. **Troubleshoot Ralph** - Debug loop issues or improve performance Wait for response before proceeding. </intake> <routing> | Response | Workflow | |----------|----------| | 1, "set up", "setup", "new", "initialize", "create" | `workflows/setup-new-loop.md` | | 2, "understand", "learn", "concepts", "explain", "how" | `workflows/understand-ralph.md` | | 3, "customize", "modify", "change", "update", "edit" | `workflows/customize-loop.md` | | 4, "troubleshoot", "debug", "fix", "problem", "issue" | `workflows/troubleshoot-loop.md` | | Other | Clarify intent, then select appropriate workflow | After reading the workflow, follow it exactly. </routing> <reference_index> ## Domain Knowledge All in `references/`: **Core Concepts:** ralph-fundamentals.md - Three phases, two prompts, one loop **Structure:** project-structure.md - Required files and directory layout **Prompts:** prompt-design.md - Planning vs building mode instructions **Backpressure:** validation-strategy.md - Tests, lints, builds as steering **Best Practices:** operational-learnings.md - AGENTS.md guidance and evolution </reference_index> <workflows_index> | Workflow | Purpose | |----------|---------| | setup-new-loop.md | Initialize Ralph structure in a directory | | understand-ralph.md | Learn Ralph concepts and philosophy | | customize-loop.md | Modify prompts or loop configuration | | troubleshoot-loop.md | Debug loop issues and improve performance | </workflows_index> <success_criteria> Skill is successful when: - User understands which workflow they need - Appropriate workflow loaded based on intent - All required references loaded by workflow - User can set up and run Ralph loops independently </success_criteria>
© Lex Christopherson · MIT · glittercowboy/taches-cc-resources