3ad4d95961
- Create professional README.md with complete feature overview, quick start guide, configuration options, best practices, and troubleshooting - Add CLAUDE.md for future Claude Code instances with architectural guidance, key commands, and operational knowledge - Transform minimal README into comprehensive project documentation - Include visual hierarchy, code examples, and clear user journey Documentation now covers the complete Ralph for Claude Code autonomous development loop system for both end users and future AI agents.
203 lines
No EOL
6.4 KiB
Markdown
203 lines
No EOL
6.4 KiB
Markdown
# Ralph for Claude Code
|
|
|
|
> **Autonomous AI development loop with intelligent exit detection and rate limiting**
|
|
|
|
Ralph is an implementation of the [Ralph technique](https://github.com/paul-gauthier/aider/blob/main/docs/more/aider-benchmarks.md#ralph) specifically designed for [Claude Code](https://claude.ai/code). It enables continuous autonomous development cycles where Claude Code iteratively improves your project until completion, with built-in safeguards to prevent infinite loops and API overuse.
|
|
|
|
## 🌟 Features
|
|
|
|
- **🔄 Autonomous Development Loop** - Continuously executes Claude Code with your project requirements
|
|
- **🛡️ Intelligent Exit Detection** - Automatically stops when project objectives are complete
|
|
- **⚡ Rate Limiting** - Built-in API call management with hourly limits and countdown timers
|
|
- **📊 Live Monitoring** - Real-time dashboard showing loop status, progress, and logs
|
|
- **🎯 Task Management** - Structured approach with prioritized task lists and progress tracking
|
|
- **🔧 Project Templates** - Quick setup for new projects with best-practice structure
|
|
- **📝 Comprehensive Logging** - Detailed execution logs with timestamps and status tracking
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### 1. Clone and Setup
|
|
|
|
```bash
|
|
git clone https://github.com/frankbria/ralph-claude-code.git
|
|
cd ralph-claude-code
|
|
./create_files.sh
|
|
```
|
|
|
|
### 2. Create Your First Project
|
|
|
|
```bash
|
|
./setup.sh my-awesome-project
|
|
cd my-awesome-project
|
|
```
|
|
|
|
### 3. Configure Your Project
|
|
|
|
Edit the generated files:
|
|
- **`PROMPT.md`** - Define your project requirements and objectives
|
|
- **`specs/`** - Add detailed specifications and requirements
|
|
- **`@fix_plan.md`** - Set initial priorities and tasks
|
|
|
|
### 4. Start the Ralph Loop
|
|
|
|
```bash
|
|
# Start autonomous development
|
|
../ralph_loop.sh
|
|
|
|
# Monitor progress (in another terminal)
|
|
../ralph_monitor.sh
|
|
```
|
|
|
|
## 📖 How It Works
|
|
|
|
Ralph operates on a simple but powerful cycle:
|
|
|
|
1. **📋 Read Instructions** - Loads `PROMPT.md` with your project requirements
|
|
2. **🤖 Execute Claude Code** - Runs Claude Code with current context and priorities
|
|
3. **📊 Track Progress** - Updates task lists and logs execution results
|
|
4. **🔍 Evaluate Completion** - Checks for exit conditions and project completion signals
|
|
5. **🔄 Repeat** - Continues until project is complete or limits are reached
|
|
|
|
### Intelligent Exit Detection
|
|
|
|
Ralph automatically stops when it detects:
|
|
- ✅ All tasks in `@fix_plan.md` marked complete
|
|
- 🎯 Multiple consecutive "done" signals from Claude Code
|
|
- 🧪 Too many test-focused loops (indicating feature completeness)
|
|
- 📋 Strong completion indicators in responses
|
|
|
|
## 🛠️ Configuration
|
|
|
|
### Rate Limiting
|
|
|
|
```bash
|
|
# Default: 100 calls per hour
|
|
../ralph_loop.sh --calls 50
|
|
|
|
# Check current usage
|
|
../ralph_loop.sh --status
|
|
```
|
|
|
|
### Custom Prompts
|
|
|
|
```bash
|
|
# Use custom prompt file
|
|
../ralph_loop.sh --prompt my_custom_instructions.md
|
|
```
|
|
|
|
### Exit Thresholds
|
|
|
|
Modify these variables in `ralph_loop.sh`:
|
|
```bash
|
|
MAX_CONSECUTIVE_TEST_LOOPS=3 # Exit after 3 test-only loops
|
|
MAX_CONSECUTIVE_DONE_SIGNALS=2 # Exit after 2 "done" signals
|
|
TEST_PERCENTAGE_THRESHOLD=30 # Flag if 30%+ loops are test-only
|
|
```
|
|
|
|
## 📁 Project Structure
|
|
|
|
Ralph creates a standardized structure for each project:
|
|
|
|
```
|
|
my-project/
|
|
├── PROMPT.md # Main development instructions for Ralph
|
|
├── @fix_plan.md # Prioritized task list (@ prefix = Ralph control file)
|
|
├── @AGENT.md # Build and run instructions
|
|
├── specs/ # Project specifications and requirements
|
|
│ └── stdlib/ # Standard library specifications
|
|
├── src/ # Source code implementation
|
|
├── examples/ # Usage examples and test cases
|
|
├── logs/ # Ralph execution logs
|
|
└── docs/generated/ # Auto-generated documentation
|
|
```
|
|
|
|
## 🎯 Best Practices
|
|
|
|
### Writing Effective Prompts
|
|
|
|
1. **Be Specific** - Clear requirements lead to better results
|
|
2. **Prioritize** - Use `@fix_plan.md` to guide Ralph's focus
|
|
3. **Set Boundaries** - Define what's in/out of scope
|
|
4. **Include Examples** - Show expected inputs/outputs
|
|
|
|
### Project Specifications
|
|
|
|
- Place detailed requirements in `specs/`
|
|
- Use `@fix_plan.md` for prioritized task tracking
|
|
- Keep `@AGENT.md` updated with build instructions
|
|
- Document key decisions and architecture
|
|
|
|
### Monitoring Progress
|
|
|
|
- Use `../ralph_monitor.sh` for live status updates
|
|
- Check logs in `logs/` for detailed execution history
|
|
- Monitor `status.json` for programmatic access
|
|
- Watch for exit condition signals
|
|
|
|
## 🔧 System Requirements
|
|
|
|
- **Bash 4.0+** - For script execution
|
|
- **Claude Code CLI** - `npx @anthropic/claude-code`
|
|
- **jq** - JSON processing for status tracking
|
|
- **Git** - Version control (projects are initialized as git repos)
|
|
- **Standard Unix tools** - grep, date, etc.
|
|
|
|
## 📊 Monitoring and Debugging
|
|
|
|
### Live Dashboard
|
|
|
|
```bash
|
|
../ralph_monitor.sh
|
|
```
|
|
|
|
Shows real-time:
|
|
- Current loop count and status
|
|
- API calls used vs. limit
|
|
- Recent log entries
|
|
- Rate limit countdown
|
|
|
|
### Status Checking
|
|
|
|
```bash
|
|
# JSON status output
|
|
../ralph_loop.sh --status
|
|
|
|
# Manual log inspection
|
|
tail -f logs/ralph.log
|
|
```
|
|
|
|
### Common Issues
|
|
|
|
- **Rate Limits** - Ralph automatically waits and displays countdown
|
|
- **Stuck Loops** - Check `@fix_plan.md` for unclear or conflicting tasks
|
|
- **Early Exit** - Review exit thresholds if Ralph stops too soon
|
|
- **Missing Dependencies** - Ensure Claude Code CLI is installed
|
|
|
|
## 🤝 Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
|
|
3. Make your changes
|
|
4. Test with `./create_files.sh` and sample projects
|
|
5. Commit your changes (`git commit -m 'Add amazing feature'`)
|
|
6. Push to the branch (`git push origin feature/amazing-feature`)
|
|
7. Open a Pull Request
|
|
|
|
## 📄 License
|
|
|
|
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
|
|
|
|
## 🙏 Acknowledgments
|
|
|
|
- Inspired by the [Ralph technique](https://github.com/paul-gauthier/aider/blob/main/docs/more/aider-benchmarks.md#ralph) from the Aider project
|
|
- Built for [Claude Code](https://claude.ai/code) by Anthropic
|
|
- Community feedback and contributions
|
|
|
|
## 🔗 Related Projects
|
|
|
|
- [Claude Code](https://claude.ai/code) - The AI coding assistant that powers Ralph
|
|
- [Aider](https://github.com/paul-gauthier/aider) - Original Ralph technique implementation
|
|
|
|
---
|
|
|
|
**Ready to let AI build your project?** Start with `./create_files.sh` and let Ralph take it from there! 🚀 |