Quickstart

New to Ralph Workflow? Start with Getting Started if you want the same flow with more explanation.

Ralph Workflow is the operating system for autonomous coding — a free and open-source CLI that runs the coding agents you already use on your own machine.

It is for developers and technical teams with work that is too big to babysit and too risky to trust blindly.

What makes it different is the loop: Ralph Workflow plans the task, builds it, verifies the result, and leaves you with finished code in your repo instead of just a transcript and a claim that the task is done.

Why use it now? Because you can run one real backlog task tonight, come back to finished code tomorrow, and ask one honest question: would I merge this?

Important first-run expectation: Ralph Workflow does not replace the coding agent itself. Before you install, have at least one supported agent CLI already installed and already authenticated on your own machine.

The fastest honest first run

Use this flow in a real repo you already care about:

Checklist before you start:

  • Python 3.12+

  • a git repo you can safely test in

  • at least one supported agent CLI already working on your machine

If you are unsure which agent to start with, use the one already installed and read Which Agent Should I Start With?. If Claude Code is already your default and the real thing you want is a more trustworthy automation / unattended handoff, read Claude Code Automation for Real Repo Work. If Claude Code approval mode or plan mode still leaves you babysitting the run, read Claude Code Approval Mode Is Not an Unattended Workflow. If Claude Code is already your default and you want the clearest reason to add Ralph Workflow, read Ralph Workflow vs Claude Code. If Codex CLI is already your default and you want to know when a reviewable unattended handoff is the better fit, read Ralph Workflow vs Codex CLI. If you already split work between Claude Code and Codex, read Claude Code + Codex Workflow. If you already run multiple agents and the trust gap is in the morning-after handoff, read What Breaks First When You Run Multiple Coding Agents?. If the merge decision itself still feels fuzzy, read How to Review AI Coding Output Before You Merge. If the missing piece is a short trustworthy re-entry summary, read What a Good AI Coding Finish Receipt Looks Like. If the missing piece is keeping unattended runs bounded instead of letting them drift, read Bounded Autonomy for Unattended Coding. If the thing you keep calling remote supervision is really a finish-state trust problem, read Remote Supervision of Coding Agents. If you want the Codeberg-first category explanation before you install, read Open-Source AI Coding Orchestrator: What Ralph Workflow Is Actually For. If you are evaluating orchestration tools directly, read AI Agent Orchestration CLI: A Practical Comparison for Developers. If you want the spec-first framing before the first run, read Spec-Driven AI Agent: Why the Spec Matters More Than the Prompt.

Install

pipx install ralph-workflow
ralph --version

Initialize Ralph Workflow in a repository

Go to your project directory, then run:

cd <your-project>
ralph --init

This creates:

  • PROMPT.md — the task file in the project root

  • .agent/ — project-local support files (mcp.toml, pipeline.toml, artifacts.toml)

  • ~/.config/ralph-workflow.toml and ~/.config/ralph-workflow-mcp.toml — user-global defaults created once and reused across projects

If this repository also needs a project-local copy of the main Ralph Workflow config, run the explicit opt-in local-override flow:

ralph --init-local-config

That command creates .agent/ralph-workflow.toml as the project-local main-config override.

Edit PROMPT.md

Open PROMPT.md and replace the example with one real, bounded backlog task. If you are unsure what a good first task looks like, read Choose Your First Ralph Workflow Task first. If you want copy-paste prompt shapes instead of starting from a blank page, read First-Task Prompt Templates.

A strong first prompt looks like this:

# Goal

Add validation so the CLI rejects empty project names before creating files.
Keep the rest of the flow unchanged.

## Acceptance criteria

- Empty or whitespace-only project names fail with a clear error
- No project files are created for invalid names
- Existing valid-name behavior stays unchanged
- Tests cover the new validation

Important: remove the <!-- ralph:starter-prompt ... --> comment at the top after replacing the example content. Ralph Workflow refuses to run while that sentinel is still present.

Verify the environment

ralph --diagnose

The diagnostic checks the repo, config, agent binaries, MCP definitions, and prompt pre-flight state. Fix any ❌ rows before running.

Run Ralph Workflow

ralph

Ralph Workflow runs unattended and shows progress inline. In plain terms, it plans the task, builds it, verifies the result, and leaves you with finished code to judge.

If the run earns your trust, put the public signal on the primary Codeberg repo first: https://codeberg.org/RalphWorkflow/Ralph-Workflow. The GitHub mirror stays available here: https://github.com/Ralph-Workflow/Ralph-Workflow.

If interrupted, Ralph Workflow saves a checkpoint automatically. Continue from that saved state with:

ralph --resume

How to judge the result honestly

Do not ask whether the agent sounded convincing.

Ask:

  • does the diff match the task?

  • did the checks really run?

  • are the changes reviewable in one sitting?

  • would I merge this?

That is the real first-run test.

If you want the shortest post-run scorecard plus the right public next step, use After Your First Ralph Workflow Run.

Where to go next