Ralph Workflow in 5 Minutes

You have five minutes. You want to know what Ralph Workflow actually does, not what it philosophically enables. Fair.

Here is the concrete answer.

Minute 1: It is not another AI coding tool

You already have an AI coding tool. Claude Code, Codex, OpenCode, Aider — whatever you use, keep using it. Ralph Workflow does not replace it.

Ralph Workflow is the loop engine that runs your tool. It hands the tool a scoped task, waits for the result, verifies it, decides whether to loop again or stop, and leaves you a reviewable diff when you come back.

Think of it as: your AI coding tool is the worker. Ralph Workflow is the foreman.

Minute 2: Install

pip install ralph-workflow

Create a workflow file — this is a plain workflow.md that describes the Default Ralph Loop:

# plan
Write a plan for the task in plan.md. Keep it specific: what files change, what the
expected outcome is, and what must stay untouched.

# develop
Implement the plan. Keep changes minimal and scoped. Do not refactor code you are not
supposed to touch.

# review
Review the diff. Check that the plan was followed, tests pass, and nothing unexpected
changed.

# verify
Run the project's test suite. If tests fail, loop back to develop with the failure output.
If they pass, write a summary in result.md and stop.

That is the simplest form. But it already does more than a naked agent run: it makes sure the agent planned before coding, checked itself after coding, and verified before claiming success. Those three gates are where most unattended runs fall apart.

Minute 3: Run it

ralph run --task "Add a rate limiter middleware to the API server"

Ralph Workflow picks up your workflow, launches the AI agent with the task context, and runs through the loop:

1. plan → the agent writes plan.md
2. develop → the agent implements the plan
3. review → the agent reviews its own diff
4. verify → the agent runs tests

If verify fails, the agent loops back to develop with the failure output. This keeps happening until verify passes or the agent hits its retry limit (default: 3).

If the agent gets stuck, Ralph Workflow detects it and stops — no infinite burn.

Minute 4: What you come back to

You get a directory that looks like this:

.runs/2026-05-30_rate-limiter/
├── plan.md          # What the agent decided to do
├── src/api/rate_limiter.py  # New code
├── tests/rate_limiter_test.py  # Tests it wrote
├── result.md        # What it thinks happened
└── session.log      # Full transcript (if you want it)

The important file is result.md. It tells you what changed, what tests passed, and whether anything was uncertain. You review the diff like a normal code review. You do not need to reconstruct the whole night.

Minute 5: Why this is different

Without Ralph Workflow	With Ralph Workflow
Agent codes and claims success	Agent plans, codes, reviews, verifies
Giant diff, confident summary	Scoped diff + test evidence
Failed runs burn tokens indefinitely	Retry cap + dead-end detection
You audit the entire transcript	You review the diff and result.md
One attempt per run	Up to N loops until verify passes

The difference is structural, not cosmetic. Adding a second try before giving up is not a minor tweak — it changes the failure mode from "silently wrong" to "verifiably incomplete." The loop matters more than the model.

What happens next

If you want the full picture:

• How to Run Claude Code Unattended — detailed mechanics of making unattended runs reliable
• How to Structure Autonomous AI Agent Workflows for Production Reliability — when you need more than the default loop
• Is Ralph Workflow Right for Your Project? — a 4-stage decision framework

Or just install it, write a three-line workflow, and run it on something small. The best way to understand the loop is to see it complete one.

---

Start here → Ralph-Workflow on Codeberg