Ralph Loop

Updated Jun 24, 2026 ·

Overview

The Ralph loop is a simple agentic coding workflow.

Instead of asking Claude Code to build a large feature in one long request, Ralph gives Claude a task list and asks it to complete one unfinished task per iteration.

The loop repeats this cycle:

1. Pick one task where passes is false.
2. Implement only that task.
3. Run the relevant validation.
4. Mark the task as complete.
5. Record progress.
6. Commit the change when appropriate.

This keeps the work smaller and easier to review.

The Ralph loop (also known as the "Wiggum loop") is named after Ralph Wiggum, a character in The Simpsons who is known for his naive persistence. The Ralph loop is a simple way to let Claude Code work through a project with minimal human intervention.

Core Files

A Ralph loop usually needs three files.

File	Purpose
ralph.sh	Runs Claude Code repeatedly with the same workflow prompt.
prd.json	Stores the task list and each task's passes status.
agent-progress.txt	Records what happened across iterations.

The agent-progress.txt file is a simple text file generated by the Ralph loop that records what happened in each iteration. It can be used to track progress, note blockers, and provide context for the next iteration.

Note that for Ralph loop to work, the project must have clear guidance files that will provide context for Claude Code to understand the project requirements, coding standards, and agent behavior. These files are:

• SPEC.md
• CLAUDE.md
• AGENTS.md

You can also have more than one specification file, but the Ralph loop will need to know which files to read for guidance. The prompt inside the Ralph loop script should specify which files to read.

For exmaple, you can have a spec folder with multiple specification files, and the Ralph loop script can specify which files to read from that folder.

├── specs
│   ├── test-api-client.md
│   ├── test-auth.md
│   ├── test-config.md
│   └── test-db-operations.md
|
├── CLAUDE.md
├── SPEC.md
├── AGENTS.md

Before proceeding with the Ralph loop, make sure these files are present and contain the necessary information for Claude Code to work effectively.

Basic Script

A sample Ralph loop script can be found here: ralph.sh

The shell script accepts a maximum iteration count. For example, to run the Ralph loop for 5 iterations, you would execute:

./ralph.sh 5

Inside the script, the loop will call Claude Code with the same prompt each time, passing in the task list, progress log, and project instructions.

The prompt instructs Claude Code to pick one task from prd.json where passes is false, implement it, validate it, mark it as complete, and update the progress log.

A sample Ralph loop script can be found here: prd.json

Sample prompt used in the Ralph loop:

claude --dangerously-skip-permissions -p "@prd.json @agent-progress.txt @SPEC.md @CLAUDE.md

Pick one task from prd.json where passes=false.

You donot need to pick tasks in file order. Choose the next task based on dependency and risk.

Implement only that task and use SPEC.md and CLAUDE.md to guide your implementation.

Run the relevant validation like lint, build, and tests. If the validation fails, do not mark the task as complete. Record any blockers in agent-progress.txt.

After the task is complete:

- Mark passes=true for that task only.
- Update agent-progress.txt.
- Ensure working tree contains only the intended task changes.
- Commit the change.

When all tasks have passes=true, output:
<complete>ALL_TASKS_DONE</complete>
"

Note: The --dangerously-skip-permissions flag gives Claude Code broad permission to edit and run commands. Use it only in a trusted local project with Git history and a reviewed task list.

To keep the Ralph loop safe, it is recommended to run it in a sandboxed environment, such as Docker or a virtual machine, to prevent unintended changes to your system.

For example, you can enable sandbox mode in Claude Code by adding the following to your .claude/settings.json file:

{
  "sandbox": {
    "enabled": true
  }
}

Task List Format

The task list is defined in the prd.json file and can be a JSON array.

A sample Ralph loop script can be found here: prd.json

Each task should be specific enough that Claude can complete it in one focused iteration.

Example:

[
  {
    "category": "database",
    "description": "Verify Prisma and Neon PostgreSQL database setup",
    "steps": [
      "Use prisma/schema.prisma as the database source of truth",
      "Verify datasource provider is postgresql",
      "Verify lib/db.ts uses PrismaNeon with DATABASE_URL",
      "Run bun run db:generate",
      "Run bun run build or document any missing environment blocker"
    ],
    "passes": false
  }
]

The important field is passes.

Claude should only pick tasks where passes is false. When the task is finished and validated, Claude changes that task to true.

Choosing Tasks

Ralph does not need to complete tasks in file order.

It is usually better to let Claude choose the next task based on dependency and risk.

Good ordering principles:

• Check project instructions before implementation.
• Do foundation work before interface polish.
• Handle risky integrations before routine UI.
• Validate security and authorization before adding convenience features.
• Keep broad cleanup tasks near the end.

Validation

Ralph works best when every task has a validation step.

For a Next.js project, a simple validation ladder might be:

bun run lint
bun run build
bunx playwright test

It is recommended to run the smallest useful validation first. A text-only documentation change does not need the same checks as an authentication or database change.

Additionally, Claude should record blockers honestly. For example, if DATABASE_URL is missing or the dev server is not running, it should write that in agent-progress.txt and avoid marking the task complete.

Project-Specific Instructions

The prompt inside the Ralph script should define the actual tool stack that will be used by Claude Code. This is important because Claude may otherwise assume a different stack and create code that does not work.

For example, the Probably Important app uses:

• Next.js 16 and React 19
• Bun as the package manager
• Node runtime for Next.js
• Prisma 7
• Neon PostgreSQL
• better-auth
• TipTap
• Playwright

In this case, if Claude Code were to assume SQLite, it would create code that does not work.

Sample project-specific rule:

Do not use SQLite or Bun SQLite. Persistence goes through Prisma and Neon PostgreSQL.

Progress Log (agent-progress.txt)

The progress file gives the loop memory between iterations.

It should include:

1. The task completed
2. Files changed
3. Validation commands run
4. Validation results
5. Blockers or follow-up notes

This helps the next iteration avoid repeating work.

When To Use Ralph

Ralph loop can be usedwhen a project has many clear tasks and each task can be validated independently.

Good use cases:

• Building out a planned application from a specification
• Working through a test backlog
• Migrating a project one area at a time
• Auditing authorization, validation, and routing
• Turning a rough prototype into a more complete app

Avoid Ralph when the task is still vague. In that case, use planning first and create the task list after the project direction is clearer.

Example In Practice

See Ralph in action in the Probably Important project documentation:

Probably Important