How to Ralph: Build Software with AI Agents

Ralph is an open-source template that turns Claude Code into a team of specialized AI agents that plan, build, and review your software — in parallel. You describe what you want. Ralph figures out the tasks, assigns them to the right agents, and builds it.

This guide walks you through every step, from zero to a working project. No prior AI experience needed.

Table of Contents

• The Big Picture
• Milestone 1: Install Claude Code
• Milestone 2: Clone the Ralph Template
• Milestone 3: Describe Your Project
• Milestone 4: Plan with AI Agents
• Milestone 5: Build with Ralph Loop
• Milestone 6: Review & Ship
• Key Concepts
• Tips & Troubleshooting

The Big Picture

Traditional development: you write code line by line. With Ralph: you describe what you want, AI agents plan the work, then AI agents build it — all while you stay in control.

Ralph strictly separates planning from building. Planning agents design your product and write tasks. Building agents (Ralph Loop) execute those tasks — one per agent, in parallel, each in an isolated workspace so they never step on each other.

Milestone 1: Install Claude Code

Claude Code is a command-line tool that lets you talk to Claude directly in your terminal. Ralph runs inside Claude Code.

Milestone 2: Clone the Ralph Template

The template gives you a pre-configured project structure with all the agent definitions, skills, and workflow files Ralph needs.

Here's what each file does:

CLAUDE.md	Project config — tech stack, commands, conventions
PRD.md	Product requirements — what you're building and why
TASKS.md	Task queue — what needs to be done, in order
PROGRESS.md	Build log — what's been completed
PROMPT.md	Agent instructions — rules every builder follows
agents/	Role definitions for each specialist agent

Milestone 3: Describe Your Project

Start Claude Code in your project directory and tell it what you want to build. Claude will fill in the template files for you.

Claude will update CLAUDE.md with your tech stack and commands, and PRD.md with your product requirements. Review these files — they're the blueprint everything else is built from.

Milestone 4: Plan with AI Agents

Ralph has three planning agents. They design your product and create tasks but never write code. This keeps planning clean and focused.

The Product Designer reads your PRD, breaks the project into atomic tasks, orders them by dependency, and writes them to TASKS.md. Each task gets an agent tag like [@frontend] or [@backend] that tells Ralph which specialist to assign.

The Architect adds infrastructure tasks (database setup, auth system, deployment config) and ensures they're ordered before the features that depend on them.

Open TASKS.md and review. You'll see something like:

## DEPS
2:1 3:1 4:2,3 5:4

## TODO
- [ ] Task 1: [ARCH] Set up Next.js with TypeScript — ... [@devops]
- [ ] Task 2: [ARCH] Set up Postgres schema — ... [@database]
- [ ] Task 3: Build recipe API endpoints — ... [@backend]
- [ ] Task 4: Build recipe list page — ... [@frontend]
- [ ] Task 5: Add search by ingredient — ... [@fullstack]

## TODONE

The DEPS section at the top defines dependencies: 2:1 means task 2 can't start until task 1 finishes. Ralph uses this to figure out what can run in parallel.

Milestone 5: Build with Ralph Loop

This is where the magic happens. Ralph Loop reads your task list, launches parallel AI agents, and builds your project — task by task, each in an isolated git worktree.

That's it. Ralph takes over:

1. Reads TASKS.md — finds tasks with satisfied dependencies
2. Launches agents in parallel — up to 3 at a time, each in its own workspace
3. Each agent completes one task — writes code, writes tests, verifies everything passes
4. Merges back to main — handles merge conflicts automatically
5. Unblocks the next tasks — launches more agents as dependencies are satisfied
6. Repeats until done

What each agent does per task

Every agent must pass a hard verification gate before committing: the build must succeed and all tests must pass. If something fails, the agent fixes it and tries again. No broken code gets merged.

You'll see real-time output as agents complete tasks. When Ralph finishes, it prints a summary:

╔══════════════════════════════════════╗
║  Ralph Loop complete!                ║
╚══════════════════════════════════════╝

  Completed:  5 tasks
  Failed:     0 tasks
  Remaining:  0 tasks

  2m 14s  sonnet  Task 1: Set up Next.js
  1m 58s  sonnet  Task 2: Set up Postgres schema
  3m 21s  sonnet  Task 3: Build recipe API
  2m 45s  sonnet  Task 4: Build recipe list page
  4m 12s  sonnet  Task 5: Add search

Milestone 6: Review & Ship

The Code Reviewer reads the git diffs and PROGRESS.md, checks for bugs, security issues, missing tests, and pattern violations. It creates follow-up tasks for anything that needs fixing — which you can run through Ralph Loop again.

Run the project locally and try it out. The build command is in CLAUDE.md — the Architect set it up for you.

Your code is already committed with descriptive messages. Push to GitHub and deploy however you like.

Key Concepts

Agent Tags

Every task gets a tag that tells Ralph which specialist to use:

[@frontend]	UI, components, styling, accessibility
[@backend]	APIs, business logic, middleware
[@database]	Schema, migrations, queries
[@fullstack]	End-to-end features spanning front and back
[@devops]	CI/CD, deployment, infrastructure
[@qa]	Test infrastructure, E2E testing
[@security]	Auth, encryption, input validation

Model Tags

By default, agents use Claude Sonnet (fast and capable). Add tags for harder tasks:

[OPUS]	Uses Claude Opus — for deep reasoning, complex architecture
[MATH]	Uses Claude Opus — for complex calculations
[MILESTONE]	Marks important checkpoints (triggers full E2E tests)
[E2E]	Triggers end-to-end test suite

Dependencies

The DEPS section in TASKS.md controls execution order. Format: child:parent or child:parent1,parent2 for multiple dependencies.

## DEPS
2:1 3:1 4:2,3 5:4

# Task 1 runs first (no dependencies)
# Tasks 2 and 3 run in parallel after 1 finishes
# Task 4 waits for both 2 and 3
# Task 5 waits for 4

Worktrees

Each agent gets its own git worktree — a separate copy of the repo. This means three agents can edit different files at the same time without conflicts. When they're done, Ralph merges everything back to main.

Verification Gate

No code gets committed without passing two checks:

1. Build — the project must compile cleanly
2. Tests — all tests must pass (unit tests always, browser tests for frontend work)

If either fails, the agent fixes the issue and re-runs. This is non-negotiable — it's a hard gate.

Tips & Troubleshooting

Start small

Your first Ralph project should be something you could build yourself in a day. A todo app, a blog, a CLI tool. This lets you understand the workflow before tackling bigger things.

Edit the tasks

The planning agents give you a draft. Read every task. Rewrite ones that are vague. Delete ones you don't need. Add details. The clearer the task descriptions, the better the output.

External dependencies

Ralph can't start Docker containers or external services itself. If your project needs a database or other service running, Ralph will print an ACTION REQUIRED message telling you exactly what to run. Start the service, then re-run the loop.

If a task fails

Ralph will report failures in the summary. Check PROGRESS.md for details. You can fix the issue manually and mark the task done, or update the task description and run the loop again.

Iterating

The workflow is designed to be repeated. After the first pass, you might want to add features, fix issues the Code Reviewer found, or change direction. Just update TASKS.md with new tasks and run the loop again. Ralph picks up where it left off.

Get Started

Ralph is open source and free to use. The template has everything you need.

git clone https://github.com/chomey/ralph-template.git my-project
cd my-project
claude

Tell Claude what you want to build. The agents take it from there.

Source: github.com/chomey/ralph-template