Ralph Templates - Autonomous AI Coding Loop System
FOR AI AGENTS: This repository contains templates for running autonomous coding loops. Read this document completely before selecting a template. This README is specifically designed for AI agent consumption.
CHOOSE YOUR MODE
This repository supports three modes of operation:
| Mode | Use When | Location | Recommended |
|------|----------|----------|-------------|
| MCP Server | Any MCP client (Claude Desktop, Claude Code, etc.) | mcp-server/ | YES |
| CLI Mode | Shell-based automation with Claude Code | RalphTemplate-*/ | For automation |
| SDK Mode | Building custom agents with Anthropic SDK | sdk/ | For developers |
Which setup do you prefer?
│
├─ I want tools in Claude Desktop or Claude Code
│ → Use MCP Server (RECOMMENDED)
│ See: mcp-server/README.md
│
├─ I want a shell script that runs autonomously
│ → Use CLI Mode (templates in root directories)
│ See: QUICK TEMPLATE SELECTOR below
│
└─ I'm building my own agent with Anthropic SDK
→ Use SDK Mode
See: sdk/README.md
MCP Server (Recommended)
The easiest way to use Ralph. Just configure the MCP server and Claude has all the tools.
# Install
cd mcp-server && npm install && npm run build
# Add to Claude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"ralph": {
"command": "node",
"args": ["/path/to/mcp-server/dist/index.js", "--project-dir", "/path/to/project"]
}
}
}
Then ask Claude: "Use Ralph tools to work on the next story"
See mcp-server/README.md for full setup instructions.
QUICK TEMPLATE SELECTOR (CLI Mode)
Use this decision tree to select the correct template:
Do you need to BUILD/WRITE code?
│
├─ YES → Is this a NEW project (no existing code)?
│ │
│ ├─ YES → RalphTemplate-FullBuildFromScratch
│ │
│ └─ NO (adding to existing codebase) → RalphTemplate-NewFeatureExistingApp_FullBuild
│
└─ NO (testing only) → What type of testing?
│
├─ Backend API endpoints only → RalphTemplate-BackEndTest
│
├─ Browser/UI flows only → RalphTemplate-ClaudeCodeBrowser
│
└─ Both API + Browser → RalphTemplate-BackEndTest&ClaudeCodeBrowser
WHAT IS RALPH?
Ralph is an autonomous AI coding loop that runs Claude Code repeatedly until all tasks are complete.
Core Principle
"Ralph is an agent that forgets on purpose. The memory is not the chat—it's the filesystem + git."
— @agrimsingh
How It Works
┌─────────────────────────────────────────────────────────┐
│ RALPH LOOP │
├─────────────────────────────────────────────────────────┤
│ 1. Read prompt.md (instructions) │
│ 2. Read prd.json (all tasks + status) │
│ 3. Read progress.txt (learnings from past iterations) │
│ 4. Find highest priority task where passes=false │
│ 5. Complete that ONE task fully │
│ 6. Git commit the changes │
│ 7. Update prd.json: set passes=true for that task │
│ 8. Append learnings to progress.txt │
│ 9. Context resets → Loop back to step 1 │
│ │
│ STOP when: ALL tasks have passes=true │
│ Output: <promise>COMPLETE</promise> │
└─────────────────────────────────────────────────────────┘
Memory Persistence Across Context Resets
| Storage | What It Holds | Persists? |
|---------|---------------|-----------|
| prompt.md | Instructions, templates, codebase patterns | Yes |
| prd.json | Task definitions, acceptance criteria, pass/fail status | Yes |
| progress.txt | Learnings discovered during previous iterations | Yes |
| Git commits | All code changes | Yes |
| Chat history | Current conversation | NO - resets each iteration |
TEMPLATE COMPARISON MATRIX
| Template | Builds Code | Backend Tests | Browser Tests | For New Projects | For Existing Code |
|----------|-------------|---------------|---------------|------------------|-------------------|
| FullBuildFromScratch | YES | YES (REL phase) | YES (REL phase) | YES | NO |
| NewFeatureExistingApp_FullBuild | YES | YES (REL phase) | YES (REL phase) | NO | YES |
| BackEndTest | NO | YES | NO | NO | YES |
| ClaudeCodeBrowser | NO | NO | YES | NO | YES |
| BackEndTest&ClaudeCodeBrowser | NO | YES | YES | NO | YES |
TEMPLATE 1: FullBuildFromScratch
Location:RalphTemplate-FullBuildFromScratch/
Use When: Building a complete new application from nothing.
Task Flow
US-000 (priority 0) → Project scaffolding (CRITICAL - see safety warning)
US-001 to US-XXX → Feature implementation stories
REL-001 → Create platform-overview.md
REL-002 → Create comprehensive-test-suite/
REL-003 → Run all tests, verify passing
REL-004 → Browser test UI with Claude-in-Chrome
REL-005 → Create RELEASE_CHECKLIST.md
CRITICAL: Scaffolding Safety
WARNING: Running npx create-next-app . or similar scaffolding tools in the project root WILL DELETEscripts/ralph/, destroying Ralph's configuration mid-loop.
SAFE PROCEDURE (always use this):
# Step 1: Scaffold to TEMP directory
npx create-next-app temp-scaffold --typescript --tailwind --eslint
# Step 2: Move files, preserving scripts/ralph
mv temp-scaffold/* ./
mv temp-scaffold/.* ./ 2>/dev/null
# Step 3: Clean up
rm -rf temp-scaffold
# Step 4: VERIFY ralph files still exist
ls scripts/ralph/prd.json # MUST exist!
| Problem | Likely Cause | Solution |
|---------|--------------|----------|
| scripts/ralph/ directory deleted | Ran scaffolding tool in project root | Use temp directory method (see safety warning above) |
| Story keeps failing repeatedly | Story too big or criteria too vague | Split into smaller stories with explicit criteria |
| "prompt.md not found" error | Initialization didn't complete | Run init script again |
| Max iterations reached | Too many stories or stories too complex | Reduce scope, make stories smaller |
| Tests failing | Code has bugs or tests incomplete | Fix code or refine test acceptance criteria |
| Won't advance to next story | Previous story passes still false | Verify criteria met, manually update prd.json if needed |
| Browser tests not working | Claude-in-Chrome MCP not configured | Set up MCP, ensure Chrome is open |
| API tests fail with 401 | Auth not working | Verify testCredentials in prd.json |
STOP CONDITION
Ralph stops when ALL stories in prd.json have passes: true:
If you're using the Anthropic SDK directly (not Claude Code CLI), use the SDK implementations:
Python
cd sdk/python
pip install -e .
from ralph import run_ralph
result = run_ralph(
project_dir="./my-project",
custom_tools=my_file_and_bash_tools,
custom_tool_handler=my_tool_handler,
max_iterations=25
)
TypeScript
cd sdk/typescript
npm install && npm run build
import { runRalph } from "ralph-sdk";
const result = await runRalph({
projectDir: "./my-project",
customTools: myTools,
customToolHandler: myHandler,
maxIterations: 25,
});
SDK vs CLI Comparison
| Aspect | CLI Mode | SDK Mode |
|--------|----------|----------|
| Setup | Copy template, run ralph.sh | Install package, write code |
| Loop control | Bash script | Your application code |
| Tool implementation | Claude Code built-ins | You implement (file, bash) |
| Flexibility | Fixed | Full control |
| Best for | Quick tasks | Custom agents, integrations |