A starter kit for building apps using the Ralph methodology — autonomous AI coding loops that ship features while you sleep.
Ralph is an autonomous coding loop where an AI agent works through a task list iteration by iteration until everything is done. No babysitting. No copy-pasting. Just describe what you want, and let Ralph build it.
This repo is a template to get you started with Ralph-style development using your favorite AI coding agent.
Inspired by Ryan Carson and Matt Pocock's Ralph tutorial on X.
| Agent | CLI | Docs |
|---|---|---|
| Claude Code | claude |
anthropic.com/claude-code |
| OpenCode | opencode |
opencode.ai |
| Amp | amp |
amp.dev |
Before you start, make sure you have:
- jq — JSON processor (
brew install jqon macOS) - Your agent CLI installed and authenticated:
- Claude Code:
claudeCLI logged in - OpenCode:
opencodeCLI configured - Amp:
ampCLI authenticated
- Claude Code:
git clone https://github.com/yourusername/ralphzilla.git my-app
cd my-appStart your AI agent and invoke the plan command:
/plan
This kicks off an intensive PRD planning session. Ralph will quiz you relentlessly about your app idea until every atomic detail is figured out. Don't hold back — answer everything.
💡 Tip: Let Ralph ask you as many questions as it wants. The more detail you provide upfront, the better the output.
The result: docs/prd.md — your complete Product Requirements Document.
Once your PRD is ready:
/tasks
This converts your PRD into docs/tasks.json — a structured task list that Ralph will execute autonomously.
Create docs/prompt.md with the instructions for each Ralph iteration. This tells Ralph what to do each time it runs.
Open ralph.sh and uncomment the line for your agent:
# For Claude Code (default):
OUTPUT=$(cat "$SCRIPT_DIR/docs/prompt.md" | claude -p --dangerously-skip-permissions 2>&1 | tee /dev/stderr) || true
# For Amp:
# OUTPUT=$(cat "$SCRIPT_DIR/docs/prompt.md" | amp --dangerously-allow-all 2>&1 | tee /dev/stderr) || true
# For OpenCode:
# OUTPUT=$(cat "$SCRIPT_DIR/docs/prompt.md" | opencode run --agent ralph 2>&1 | tee /dev/stderr) || truechmod +x ralph.sh
./ralph.sh 10 # Run up to 10 iterationsRalph will loop through iterations, working through your tasks. When all tasks are complete, it outputs <promise>COMPLETE</promise> and exits.
ralphzilla/
├── ralph.sh # The main loop script
├── docs/
│ ├── prd.md # Your PRD (created by /plan)
│ ├── tasks.json # Your tasks (created by /tasks)
│ └── prompt.md # Instructions for each iteration
├── tmp/
│ └── progress.txt # Ralph's progress log
├── archive/ # Archived runs from previous features
├── .agents/ # Main commands & skills folder
├── .claude/ # Symlink → .agents
├── .opencode/ # Symlink → .agents
├── CLAUDE.md # Agent instructions
└── opencode.json # OpenCode config
💡 Note:
.claude/and.opencode/are symlinks to.agents/. This means you only need to edit files in.agents/once, and all agents share the same commands and skills. No duplication needed!
┌─────────────────────────────────────────────────────────┐
│ YOU │
│ │ │
│ Describe your idea │
│ ▼ │
│ ┌──────────┐ │
│ │ /plan │ Quiz until atomic clarity │
│ └────┬─────┘ │
│ ▼ │
│ docs/prd.md │
│ │ │
│ ┌────┴─────┐ │
│ │ /tasks │ Break into executable tasks │
│ └────┬─────┘ │
│ ▼ │
│ docs/tasks.json │
│ │ │
│ ┌────┴─────┐ │
│ │ ralph.sh │ Autonomous loop │
│ └────┬─────┘ │
│ │ │
│ ┌─────────┼─────────┐ │
│ ▼ ▼ ▼ │
│ Iteration Iteration Iteration │
│ 1 2 ...N │
│ │ │ │ │
│ └─────────┴─────────┘ │
│ │ │
│ ▼ │
│ ✅ COMPLETE │
│ │
│ Your app is built! │
└─────────────────────────────────────────────────────────┘
Starts an intensive PRD session. Ralph will:
- Quiz you relentlessly about your app idea
- Ask about edge cases, user flows, error states
- Not stop until every detail is crystal clear
- Generate
docs/prd.mdwhen satisfied
Converts your PRD to executable tasks:
- Reads
docs/prd.md - Breaks it into small, atomic user stories
- Orders by dependency (schema → backend → UI)
- Outputs
docs/tasks.json
-
Let Ralph quiz you thoroughly — The
/planphase is where the magic happens. Don't rush it. Answer every question in detail. -
Keep tasks atomic — Each task should be completable in one iteration. If Ralph suggests breaking something down, trust it.
-
Review tasks.json before running — Glance at the generated tasks to make sure they make sense.
-
Start small — Try a simple feature first to get comfortable with the workflow.
-
Check progress.txt — Ralph logs its progress in
tmp/progress.txt. Check it to see what's happening.
Ralph automatically archives previous runs when you switch branches:
- Archives go to
archive/YYYY-MM-DD-feature-name/ - Contains the old
tasks.jsonandprogress.txt - Lets you track multiple features/experiments
This repo includes an opinionated setup for the Chrome DevTools MCP server, which lets Ralph interact with a browser for UI verification.
Step 1: Open Chrome with remote debugging enabled:
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
# Linux
google-chrome --remote-debugging-port=9222
# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222Step 2: The MCP config (.mcp.json) is already set up to connect to this:
{
"mcpServers": {
"chrome-devtools": {
"command": "chrome-devtools-mcp",
"args": [
"--browserUrl",
"http://127.0.0.1:9222",
"--categoryNetwork=false",
"--categoryEmulation=false",
"--categoryPerformance=false"
]
}
}
}
⚠️ This assumeschrome-devtools-mcpis installed globally. If not, see alternatives below.
If you don't have chrome-devtools-mcp installed globally, change the command to use npx:
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["chrome-devtools-mcp", "--browserUrl", "http://127.0.0.1:9222"]
}
}
}If you don't want to manually open Chrome, remove the --browserUrl argument. The MCP server will find and launch Chrome automatically:
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["chrome-devtools-mcp"]
}
}
}💡 The manual approach (
--browserUrl) is more predictable and gives you control over which Chrome instance Ralph uses.
MIT — Use it, fork it, ship with it. 🚀
Now go build something awesome. 🦸