Ralph is an autonomous coding loop powered by Claude. It implements features one small task at a time, maintaining a living spec that documents progress.

This is my implementation of the idea originally described by Geoffrey Huntley.

1. You write a spec describing what you want to build
2. Ralph loops, each iteration:
   • Reads the spec
   • Picks the most important next task
   • Implements it
   • Updates the spec with what was done
   • Commits the changes
   • Restarts for the next task

• spec.md - The living documentation: what to build, what's done, work log
• prompt.md - Instructions Ralph follows each iteration
• setup-prompt.md - Used to create a new spec interactively
• run-loop.sh - The bash script that runs the loop
• hooks/end-iteration.sh - Stop hook that enforces clean commits

1. Clone this repo
2. Copy it into a .ralph folder in your project's working directory
3. Add .ralph/ to your .gitignore

git clone https://github.com/larryhudson/ralph-loop.git
cp -r ralph-loop /path/to/your/project/.ralph
echo ".ralph/" >> /path/to/your/project/.gitignore

# Start Ralph (creates spec interactively if needed)
bash .ralph/run-loop.sh

# Stop the loop
# Press Ctrl+C during the sleep between iterations

The spec (spec.md) is living documentation - it describes what we're building and evolves as implementation progresses. Focus on acceptance criteria (what success looks like) rather than implementation details (how to build it).

Ralph uses a Claude Code Stop hook (hooks/end-iteration.sh) that:

1. Blocks stopping if there are uncommitted changes
2. Kills the Claude process to restart the loop when done

This ensures every iteration ends with a clean git commit.

• One task per iteration - Small, focused changes
• Living documentation - The spec stays accurate and useful
• Clean commits - Every iteration produces a commit
• Adaptive - Ralph can update the plan when it learns something new