Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add glittercowboy/taches-cc-resources
/plugin install taches-cc-resources@taches-cc-resources
Open on GitHub

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

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

3Manually: put the files in place

~/.claude/skills/setup-ralph/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/setup-ralph/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set48

The whole set →
ask-me-questions ask-me-questions is a Claude Code command that gathers requirements before a task begins. It asks about missing details and waits for the user to approve execution. CX Codex +1 ★ 1,988repo stars heal-skill heal-skill — a command to update skill documentation based on errors discovered during execution. Shows proposed changes, waits for approval, then applies edits with optional commit. CX Codex +1 ★ 1,988repo stars whats-next whats-next analyzes the current conversation and writes a detailed handoff document to resume work in a fresh context. CX Codex +1 ★ 1,988repo stars the-pirate-bay Search The Pirate Bay through its JSON API and retrieve magnet links. Use it to find torrents, browse popular uploads, or check seed counts. CX Codex +1 ★ 1,988repo stars run-plan run-plan executes a PLAN.md file directly without loading planner skill overhead. It routes tasks to subagents and keeps most of the context window free. CX Codex +1 ★ 1,988repo stars build-macos-apps build-macos-apps is a Claude Code skill for building native macOS apps with SwiftUI and AppKit. It routes work on new apps, bugs, tests, performance, and releases to a matching workflow. CX Codex +1 ★ 1,988repo stars options A command to evaluate multiple options side-by-side: tools, approaches, architectures. It asks clarifying questions, builds a comparison matrix, and recommends the best choice with reasoning. CX Codex +1 ★ 1,988repo stars competitive competitive researches competitors for any feature or product, maps market gaps, and saves a markdown report to your project. CX Codex +1 ★ 1,988repo stars

Project sponsors

Companies that keep this analytics open