Autonomous AI agent loop for feature development with a superior 4-layer learning system
Ralph automates software development by running Claude Code CLI in an iterative loop, implementing user stories one at a time while learning from its own progress.
Lineage: Originally conceived by Geoffrey Huntley, adapted for Amp CLI by snarktank, and now enhanced for Claude Code CLI with automatic conversation tracking, insight extraction, and a superior 4-layer learning system.
- 🔄 Autonomous Iteration - Runs until all PRD tasks complete
- 🧠 4-Layer Learning System - Patterns, progress logs, git history, and full conversation logs
- 📊 Auto-Session Tracking - Captures conversation IDs automatically
- 💡 Auto-Insight Extraction - Analyzes conversations for patterns and gotchas
- 🌐 Browser Testing - Visual verification for UI changes (optional)
- 📝 Structured Learnings - Future iterations learn from past mistakes
- 🎨 Interactive Flowchart - Visual walkthrough of Ralph's workflow
# Clone into your project
cd /path/to/your/project
mkdir -p scripts
cd scripts
git clone https://github.com/ardmhacha24/ralph-claude-code.git ralph
cd ralph# Option A: Interactive setup (recommended)
./init.sh
# Option B: Manual setup
# See SETUP.md for instructions# Interactive creator
./create-prd-interactive.sh
# Or copy an example
cp examples/simple-ui-fix.prd.json prd.json
# Edit prd.json with your stories./ralph.sh 10- SETUP.md - First-time setup instructions
- QUICKSTART.md - Detailed getting started guide
- ARCHITECTURE.md - Technical deep dive
- LEARNING_SYSTEM.md - How the 4-layer learning works
- flowchart/ - Interactive visualization
| Feature | Original Ralph (Amp) | This (Claude Code) |
|---|---|---|
| Learning Layers | 3 | 4 (added conversation logs) |
| Session Tracking | Thread URLs | Auto-captured session IDs |
| Insight Extraction | Manual | Automatic after each iteration |
| Conversation Logs | ❌ | ✅ Full JSONL logs |
| Browser Testing | Optional | Required for UI changes |
| Storage | External service | Local files (git-versioned) |
Layer 1: Codebase Patterns - Consolidated wisdom, read first every iteration
Layer 2: Progress Entries - Structured learnings with session IDs
Layer 3: Git History - Actual code changes via git show
Layer 4: Conversation Logs - Full JSONL logs for deep debugging
- Fresh Context Per Iteration - Each iteration is a new Claude instance
- Reads Previous Learnings - 4-layer learning system prevents repeated mistakes
- Implements User Story - Follows patterns from previous iterations
- Runs Quality Checks - Type checking, linting, browser testing
- Commits & Documents - Saves code and learnings for next iteration
- Auto-Captures Session - Saves conversation ID and extracts insights
- Continues Until Done - Moves to next story automatically
View the complete Ralph workflow visually:
cd flowchart
npm install
npm run dev
# Open http://localhost:5173- Claude Code CLI - Already installed if you're using Claude Code
- jq - JSON processor (usually pre-installed)
- Git - Version control
- Node.js - Only if using the flowchart visualization
- simple-ui-fix.prd.json - 3 simple stories (good for testing)
- player-search.prd.json - 4-story feature implementation
- coach-dashboard-improvements.prd.json - 6-story UI enhancement
- Start Small - Test with 1-2 story PRD first
- Keep Stories Focused - Each should complete in one context window
- Monitor Progress - Watch
progress.txtbetween iterations - Review Commits - Check quality after each iteration
- Use Patterns Section - Add discovered patterns to help future iterations
Ralph needs minimal customization for your project:
Required:
- Quality check commands (type-check, lint)
Optional:
- Browser testing credentials (for UI work)
- Project-specific patterns (coding conventions)
The init.sh script guides you through all of this.
After each iteration, Ralph automatically:
- Captures the Claude conversation ID
- Logs to
session-history.txt - Extracts insights in background
- Saves to
insights/iteration-N-[session].md
Deep dive into any iteration:
./parse-conversation.sh <session-id>This shows:
- Errors encountered
- Files modified
- Commands executed
- Git commits
- Key decisions made
Contributions welcome! This is the Claude Code CLI adaptation of Ralph, building on:
- Geoffrey Huntley's original Ralph pattern - The foundational autonomous loop concept
- snarktank's Amp CLI version - Thread tracking and 3-layer learning
Enhanced for Claude Code CLI with:
- Automatic session tracking via conversation IDs
- JSONL conversation parsing and analysis
- Background insight extraction after each iteration
- Superior 4-layer learning architecture
- Interactive setup wizard and comprehensive documentation
Same as original Ralph project.
Ralph has evolved through three generations:
-
Original Ralph Pattern by Geoffrey Huntley
- Conceived the elegant autonomous loop concept:
while :; do cat PROMPT.md | claude-code ; done - Introduced the idea of persistent memory through files between iterations
- Article: ghuntley.com/ralph
- Conceived the elegant autonomous loop concept:
-
Amp CLI Adaptation by snarktank (Ryan Carson)
- Adapted Ralph for Amp CLI with thread URLs and skills system
- Added 3-layer learning system and thread tracking
- Repository: github.com/snarktank/ralph
-
This Claude Code CLI Version by Neil Barlow
- Enhanced with 4-layer learning system (added conversation log parsing)
- Automatic session ID capture and insight extraction
- Local JSONL conversation storage for deep debugging
- Interactive setup wizard and comprehensive documentation
- Browser testing integration and quality assurance framework
- Check the documentation in the
docs/directory - Review example PRDs in
examples/ - Run
./validate-prd.shto check your PRD
Ready to automate your feature development? Run ./init.sh to get started!