Ralph Code Architecture
Ralph is a bash-based iterative loop system for Claude Code that:
- Reads a PROMPT.md file with project requirements
- Executes Claude Code with that prompt
- Analyzes the response for completion signals:
- Completion keywords (done, complete, finished)
- Test-only patterns (just running tests, no implementation)
- Error patterns (stuck loops)
- File changes via git diff
- Circuit breaker pattern prevents runaway loops:
- Opens after 3 loops with no file changes
- Opens after 5 loops with same error
- Half-open monitoring state for recovery
- Rate limiting (100 calls/hour by default)
- Graceful exit detection when objectives are met
Key Files
/opt/repos/ralph-claude-code/ralph_loop.sh- Main loop logic/opt/repos/ralph-claude-code/lib/response_analyzer.sh- Completion detection/opt/repos/ralph-claude-code/lib/circuit_breaker.sh- Stagnation prevention
Why It Works for Code
Ralph succeeds because code tasks have clear completion criteria: - Tests pass - Files change - Explicit 'done' signals
The loop lets Claude fail, learn from errors, and iterate until success.