| name | ralph |
| description | Run the autonomous ralph loop for mechanical stories. Iterates with fresh context until all tasks pass. |
| disable-model-invocation | true |
Ralph Loop Runner
Run the autonomous iteration loop for mechanical (machine-verifiable) stories.
Usage
./scripts/ralph.sh
./scripts/ralph.sh 20
./scripts/ralph.sh 15 --worktree
./scripts/ralph.sh 10 --branch feature/my-feature --worktree
Prerequisites
Before running, ensure:
prd.json exists in the project root (use /prd to generate)
shared-contracts.md exists with defined contracts (use /build-feature to generate)
jq is installed (brew install jq)
- Claude Code is installed and authenticated
How It Works
Each iteration:
- Reads
prd.json to find the highest-priority incomplete story
- Spawns a fresh Claude Code instance with
claude -p (clean context)
- Passes the story details, shared contracts, and recent learnings
- Claude implements the story, runs tests, and reports completion
- Auto-commits changes (safety net for agents that forget to commit)
- Appends learnings to
progress.txt for the next iteration
- Repeats until all stories pass or max iterations reached
Flags
| Flag | Description |
|---|
--worktree | Run in an isolated git worktree (recommended for parallel execution) |
--branch <name> | Create/use a specific branch for the work |
Running Multiple Loops in Parallel
For parallel execution on independent modules:
./scripts/ralph.sh 10 --branch feature/frontend --worktree &
./scripts/ralph.sh 10 --branch feature/backend --worktree &
wait
IMPORTANT: Only parallelize loops that work on completely different files. Never run two loops on overlapping files.