Ralph Loop with Claude Code Tasks Template

A GitHub template repository for autonomous AI-driven software development using Claude Code.

What is the Ralph Loop?

The Ralph Loop is an autonomous development methodology where Claude operates as an agent that iteratively:

1. Picks a task from a persistent task list
2. Implements it
3. Verifies tests pass (backpressure)
4. Commits changes
5. Exits and restarts with fresh context

By restarting after each task, Claude always operates with a clean context window at peak effectiveness. Tasks persist between sessions using Claude Code's built-in task system.

Based on the Ralph Wiggum methodology by Geoffrey Huntley.

Quick Start

1. Create a new repository from this template

Click "Use this template" → "Create a new repository"

2. Clone and configure

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO
./setup-ralph-loop-project.sh

The setup script will ask about your project and configure everything automatically.

3. Create tasks

./setup-ralph-loop.sh

This opens an interactive Claude session. Create your tasks:

Create tasks for this project:
1. Write requirements specification in specs/requirements.md
2. Write architecture document in specs/architecture.md
3. Set up project structure
4. Implement feature X
5. Add tests for feature X

4. Let it run

./ralph-loop.sh

Claude will autonomously work through the task list. To stop gracefully:

touch .ralph-stop

Prerequisites

• Claude Code CLI installed and authenticated
• Git initialized in your project
• A test suite (the loop enforces tests must pass before committing)

⚠️ Important Note

The loop runs with --dangerously-skip-permissions for fully autonomous operation. This means Claude can read/write files and execute commands without prompts. Only use on projects where you trust autonomous AI changes.

Files

File	Purpose
setup-ralph-loop-project.sh	Run first — configures the project
setup-ralph-loop.sh	Opens interactive session to create tasks
ralph-loop.sh	Runs the autonomous loop
PROMPT.md	Instructions fed to Claude each iteration
RALPH_LOOP.md	Detailed documentation

Supported Languages

The setup script includes presets for:

• Node.js / JavaScript / TypeScript
• Python
• Rust
• Go
• Ruby / Rails
• Java (Gradle / Maven)
• Custom commands

Documentation

See RALPH_LOOP.md for detailed documentation including:

• How the loop works
• Customization options
• Task dependencies
• Monitoring progress
• Troubleshooting

License

MIT