How to set up Ralph for Claude Code quickly (the real Ralph)

January 15, 2026

Claude Code reached General Availability (GA) on May 22, 2025. Since then, I’ve implemented countless commands, skills, and agents. I also wrote some bash scripts for my Claude (and Gemini), but they were never intended to fully automate workflows. Instead, they allowed me to orchestrate agents to address some of Claude’s oddities. I never automated a full implementation with Claude because I assumed it wasn’t possible without constant human oversight.

After working with CC for a year, it’s time to try a more automated approach. The one I will be experimenting with is commonly referred to as Ralph: a bash loop that runs Claude Code until your task list is done.

The Ralph Wiggum Technique

While many use a similar approach, Geoffrey Huntley coined the term Ralph Wiggum Technique, which is currently the most popular “agentic while loop.” It embodies the spirit of The Simpsons’ character: “I’m helping!”—perhaps a bit naive, but relentlessly persistent until the job is done.

while :; do claude ; done

That’s it. No frameworks. No agents. No complexity.

When you Google “Ralph Claude Code”, you will see many projects and websites. Remember: it’s just a technique. I’ve implemented a minimal version that can be installed in any existing project to test it myself.

https://github.com/tomwojcik/claude-code-ralph-boilerplate — 3 files. 30 lines of bash. Zero dependencies (beyond Claude Code itself).

my-project/
├── PRD.md          # Your task list
├── progress.txt    # Completed tasks log
└── ralph.sh        # The loop

I advise against using the existing, “complex” GitHub projects with thousands of stars.

First, the more complex the project, the more attack vectors there are. With a 30-line bash script, you can audit every single line of code that orchestrates your AI. You cannot say the same for a 5,000-line Python agent framework.

Second, if all I need is a while loop, why create those attack vectors in the first place? The more you add, the less “Ralph” it becomes.

Why Not Use the Claude Code Plugin?

Claude Code now has an official Ralph plugin that implements the technique internally. You invoke it with /ralph-loop "your prompt" --max-iterations 10.

In my opinion, this is not real Ralph. It’s backwards.

In the plugin version, you call Claude, which uses Stop hooks to orchestrate calling Claude again. The flow is:

You → Claude Code (orchestrator) → Stop hooks → Claude Code (worker)

In real Ralph, bash orchestrates Claude:

You → Bash loop → Claude Code (worker)

The orchestrator doesn’t need LLM capabilities. The plugin is simpler to invoke and more reusable, yes. Will work similarly. But the orchestration part is a while loop. You don’t need an AI agent to run a while loop. Using Claude for that just feels wrong.

Writing Effective PRD.md Files

Ralph is only as good as your task list. Here’s what makes a good PRD.md:

Be Specific and Actionable

❌ Bad: “Add authentication”
✅ Good: “Implement JWT-based login endpoint at /api/auth/login with email/password validation”

One Task = One Deliverable

Each checkbox should produce exactly one commit.
If a task feels too big, break it into subtasks.

Include Acceptance Criteria

- [ ] Add user registration endpoint
  - Must validate email format
  - Must hash passwords with bcrypt
  - Must return 201 on success
  - Must return 400 on validation errors

Order by Priority Claude reads top-down. Your most important task should always be first.

Monitoring Ralph Runs

Track with Git

# Watch commits as Ralph works
git log --oneline

# See what changed in the last commit
git show HEAD

Use Pre-commit Hooks

Ralph commits automatically, so pre-commit hooks are your quality gate:

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: tests
        name: Run tests
        entry: npm test
        language: system
        pass_filenames: false

If tests fail, the commit is blocked, and Ralph sees the error. It will fix the issue on the next iteration.

Add Playwright for Verification

For web projects, Playwright verification is powerful:

## To Do
- [ ] Create login form at /login
  - Verify: `playwright test auth.spec.ts` passes
  - Verify: Form submits to /api/auth/login
  - Verify: Success redirects to /dashboard

Alternatively, just write in your CLAUDE.md to always verify the frontend changes with Playwright.

Claude can run Playwright tests as acceptance criteria.

When Ralph Gets Stuck

Task Too Vague

Symptom: Claude loops without making progress.
Fix: Make the task more specific with clear deliverables.

Missing Dependencies

Symptom: Claude fails to install packages or set up tools.
Fix: Add prerequisites to PRD.md:

## Prerequisites
- Node.js 18+
- PostgreSQL running on localhost:5432
- Environment: Copy .env.example to .env

Test Failures

Symptom: Commit blocked by pre-commit hook.
Fix: Nothing! This is working as intended. Ralph will read the error and fix it in the next iteration.

Cost Considerations

Start with ./ralph.sh 1 to test your PRD before longer runs.
Use --model haiku for simpler tasks (cheaper model).
Set clear completion criteria so Ralph stops when done.

Ralph isn’t free, but it’s predictable. Unlike human contractors, you know exactly what you’re paying per iteration.

Try It Yourself

Get started in 10 seconds:

curl -fsSL https://raw.githubusercontent.com/tomwojcik/claude-code-ralph-boilerplate/main/setup-ralph.sh | bash

This creates:

PRD.md — Your task list
progress.txt — Completion log
ralph.sh — The loop

Edit PRD.md with your tasks:

## To Do
- [ ] Add user authentication
- [ ] Write tests for login flow
- [ ] Deploy to staging

Then run:

./ralph.sh 5  # 5 iterations

Claude will work through your list, one task at a time, committing and logging progress.

Tom Wojcik