Write your spec in PROMPT.md. Run ralph. Walk away.
Ralph executes structured plan → dev → review cycles — fresh context each iteration, no babysitting required.
Your backlog. Your high-impact deferred work. Committed and reviewed when you return.
Delivery-blocked
With Ralph
ralph. The execution loop — plan, implement, commit, clear context — runs without you watching
PHASE 1 · WRITE DETAILED SPECIFICATIONS
Think like a PM: describe what you want, the constraints, acceptance criteria, and files to update. Ralph never asks for clarification, so be thorough. Use ralph --init feature-spec to start from a template.
PHASE 2 · START THE RUN AND WALK AWAY
Run ralph and step away. Dev iterations plan, implement, commit, and clear context automatically. If interrupted, ralph --resume picks up where it stopped.
PHASE 3 · REVIEW AND MERGE WITH CONFIDENCE
Inspect the diff, check the per-iteration logs in .agent/logs/, and merge when satisfied. Ralph’s commits are auditable — each iteration and review cycle leaves its own entry in git history.
Under the Hood
Dev iteration — repeats ×N
Review cycle — repeats ×N
Ralph owns PLAN.md and ISSUES.md — agents never control orchestration files. Each iteration starts with a wiped context.
Ralph leaves clean, conventional git history. No logs to parse, no handoff notes — just the diff to review.
Output representative of a real Ralph Workflow run. Session IDs and commit hashes anonymized.
STEP 2 · Initialize
ralph --init feature-spec✓ Created PROMPT.mdEdit PROMPT.md with your detailed specification.
STEP 3 · Run & Walk Away
ralph✓ Running — come back to reviewed commitsRalph works through your spec, commits its output, and stops. No prompts. No babysitting.
HOW MUCH WORK? · CHOOSE A DEPTH
QUICK
ralph -Q
A small fix, a typo, a one-file change. Fast pass — done in minutes.
STANDARD default
ralph
Most features and tasks. The right choice when you're not sure — just run ralph.
THOROUGH
ralph -T
Complex refactors, tricky bugs, or anything where extra passes matter. Leave it running overnight.
More presets in the docs.
CATEGORY
Ralph Workflow is an unattended orchestration product. Not an interactive chat assistant. It runs structured plan → dev → review cycles while you're not there — committed and auditable when you return.
DISTINCTION
Ralph is the concept. Ralph Workflow is the product.
This site covers the ralph-workflow
CLI — not a hosted service, not the broader concept. You install the CLI; there is no Ralph server.
FIT
Best fit: deterministic, spec-driven work where auditable outputs matter — the high-impact task nobody can prioritize this week, the refactor nobody queues, the tests nobody has time to write. Not a tool for interactive pair-programming sessions.
subscriptions
0 // forever freelocal orchestration
100% // no Ralph serversAI clients
3 // Claude · Codex · OpenCoderesumable runs
∞ // checkpoint built-inNot every task deserves your focus. Ralph handles the ones that don't — while you sleep, commute, or work on something that actually needs you.
MAJOR TASK, NO BANDWIDTH
Write what you want built before dinner. Ralph runs dev and review cycles overnight — you wake up to reviewed, committed code. No babysitting required.
ralph -T
THE REFACTOR NOBODY WANTS TO TOUCH
Describe every file to touch and the rules to preserve. Ralph works through it methodically, committing as it goes — an auditable trail you can review one commit at a time.
ralph -S
TEST COVERAGE YOU KEEP PUTTING OFF
Spec the edge cases and expectations. Ralph writes them, runs them, iterates until they pass, then the reviewer checks coverage. Done without a context switch.
ralph --init test
DOCS THAT ARE ALWAYS OUT OF DATE
Define the sections, tone, and what needs covering. Ralph writes and iterates until the docs match your spec, then the reviewer checks for completeness and gaps.
ralph --init docs
Every feature designed for autonomous operation. Set it, forget it, review when ready.
CAPABILITY · WORKFLOW
Separate agents for development and review run in sequence. Quality checks are built into the pipeline, not bolted on.
CAPABILITY · GIT-NATIVE
Works inside any Git repo. Ralph operates in your worktree, branches, commits, and produces a clean final diff.
CAPABILITY · RESILIENCE
Interruptions happen. Ralph saves state at every phase so you can resume without losing progress or context.
CAPABILITY · QUALITY GATE
Dedicated review agent inspects the diff, identifies issues, and iterates on fixes — a built-in quality gate after every dev cycle.
CAPABILITY · ISOLATION
Context is cleared between phases to prevent pollution. Each agent sees only what it needs — keeping quality high across iterations.
CAPABILITY · MULTI-CLIENT
Use Claude Code, OpenAI Codex, or OpenCode as your developer and reviewer. Mix and match agents per role for best results.
CAPABILITY · PARALLEL OPS
Run Ralph on separate Git worktrees to work multiple features in parallel. Each worktree runs independently — no conflicts with your active development.
CAPABILITY · EFFICIENCY
Built in Rust — Ralph itself adds negligible overhead to your AI agent budget. The only cost is what your AI clients charge per token.
CAPABILITY · OWNERSHIP
AGPL-3.0 applies to Ralph itself, not the code it generates. Every commit it produces is yours — no license encumbrance on generated output.
Ralph orchestrates agents you already have — use any combination for developer and reviewer roles.
CLIENT · CLAUDE CODE
by Anthropic
Best for thorough feature implementation and complex reasoning tasks.
npm install -g @anthropic/claude-codeCLIENT · CODEX CLI
by OpenAI
Excellent reviewer agent. Cost-effective for review cycles and quality checks.
npm install -g @openai/codexCLIENT · OPENCODE
opencode.ai
Flexible open-source alternative suitable for both developer and reviewer roles.
# See opencode.ai for installMix & Match Agents
ralph -a claude -r codex
Claude as developer · Codex as reviewer
ralph -a opencode -r opencode
OpenCode for both roles
Supports fallback chains — Ralph automatically switches to the next configured agent if one fails.
Most AI coding tools are interactive — they wait for you to steer them. Ralph runs a structured, stateless pipeline that delivers commits while you're away.
FIELD: ISOLATION
Context resets between iterations
AI sessions accumulate noise — the model hallucinates into its own prior output and drifts from spec over time. Ralph wipes context at every phase boundary. Each dev cycle starts from PROMPT.md, not from the previous iteration’s state.
FIELD: SPEC-DRIVEN
Spec-driven, not session-driven
Write requirements once in PROMPT.md. Ralph plans, implements, commits, and reviews without asking for clarification. Separate agents handle dev and review — not one model context wearing multiple hats.
FIELD: AUDITABLE
The output is commits, not a transcript
Every iteration ends with a conventional commit. Your review workflow stays the same: inspect the diff, check the history, merge when satisfied. Ralph produces no artifacts you can’t already work with.
Rapid one-shot tasks with no checkpoint needs, single-step file transforms
Scripts exceed ~100 lines; retry logic and state management become hand-coded bugs
Triggered workflows tied to repo events; reproducible build and deploy pipelines
Tasks require conversational context, unstructured reasoning, or mid-run human approval
Custom agent topologies, dynamic routing between specialist agents, Python-native teams
Overhead is unjustified for linear plan→dev→review pipelines; framework complexity exceeds the task
Exploratory sessions, design iteration, back-and-forth with a human in the loop
Human must stay present; no unattended execution; context window limits multi-file codebases
Real-time pair programming, in-editor completions, small targeted edits with immediate feedback
Long-horizon tasks where agent needs to run, test, iterate across many files without hand-holding
Long-horizon unattended runs, multi-step agent pipelines, checkpoint-gated execution
Task fits in one prompt, no checkpoints needed, setup overhead isn't justified
Your task can be described in a single message and answered without checkpoints, branching, or multi-step execution. Use Claude directly.
You need to stay in the loop at every step. Ralph Workflow is designed for runs that complete without you — if you want hand-holding, use a chat interface.
Your task takes only a few minutes to execute manually. Ralph Workflow is optimized for long-running unattended sessions — hours, not minutes. Orchestration overhead is not justified for tasks you'd finish before coffee cools.
Your workflow involves exactly one agent with no phase handoffs, no checkpoint gates, and no parallel execution. A direct API call is simpler and faster.
Your workflow needs human input at unpredictable intervals mid-run. Ralph Workflow supports defined checkpoints, not freeform interaction mid-execution.
All code, files, and artifacts produced during a Ralph Workflow run belong to you. No vendor claim on output.
Your pipeline templates, prompt sequences, and agent configurations are your intellectual property.
Execution logs, checkpoints, and audit trails are stored locally or in your infrastructure. Ralph Workflow never retains your run data.
Ralph Workflow is AGPL-3.0. The code it generates belongs to you — review the full licence at Codeberg.
AGPL-3.0 CLI
While you sleep, Ralph ships.
The major task that never gets a dedicated sprint. The backlog item that never gets a slot. The refactor everyone avoids. Ralph handles it — AGPL-3.0 CLI that runs structured dev and review cycles, completely unattended.
AGPL-3.0 · Runs on your machine · No Ralph servers · Any Git repo