Getting Started with Ralph Workflow

New to Ralph Workflow? This page takes you from install to your first unattended run without assuming you already know the pipeline internals. If you want the same flow in shorter form, use Quickstart.

What Ralph Workflow does

Ralph Workflow is the operating system for autonomous coding — a free and open-source tool for bigger AI coding tasks on your own machine. You describe the task in PROMPT.md, Ralph Workflow runs the loop — plan, build, verify — and you come back to finished code you can judge in your normal git workflow.

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 from a normal AI coding chat is the loop: Ralph Workflow plans the task, builds it, verifies the result, and leaves you with finished code in your repo instead of a long transcript and a claim that the task is done.

Why use it now? Because you can try it with the agents you already trust on your own machine, on one real backlog task, and decide tomorrow whether the result is something you would actually merge.

Important expectation before you install: Ralph Workflow is free and open source, but it does not replace the coding agent itself. For the fastest honest first run, have at least one supported agent CLI already installed and already authenticated on your own machine before you continue.

It works well for substantial work in existing repositories as well as new ones: feature work, refactors, test expansion, documentation passes, and similar multi-file tasks.

Choose the right first task

Do not start with a vague demo.

Start with one real backlog task that is:

  • small enough to judge in one sitting

  • clear enough that success is easy to define

  • cheap to roll back if the run misses

  • real enough that you already want it done

Good first tasks:

  • a bounded feature slice

  • a narrow refactor with tests

  • a cleanup task with obvious verification

  • repetitive implementation work where done is easy to judge

Bad first tasks:

  • vague product exploration

  • risky production surgery

  • broad multi-part work with no clear stopping point

  • anything where nobody agrees what success looks like

If you want a sharper pass/fail filter before you install, read Choose Your First Ralph Workflow Task. If you are unsure whether to start with Claude Code, Codex, or OpenCode, 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 terminal, read Claude Code Approval Mode Is Not an Unattended Workflow. If Claude Code is already your default and you want the clearest answer to “why add Ralph Workflow at all?”, read Ralph Workflow vs Claude Code. If Codex CLI is already your default and you want to know when an unattended reviewable handoff is the better fit, read Ralph Workflow vs Codex CLI. If you already use Claude Code and Codex together and want a cleaner split between implementation and review, read Claude Code + Codex Workflow. If you already run multiple agents and the real pain is review/reconstruction rather than branch collisions, read What Breaks First When You Run Multiple Coding Agents?. If the part you still do not trust is the morning-after merge decision, read How to Review AI Coding Output Before You Merge. If you want the cleanest possible short handoff before you trust the run, read What a Good AI Coding Finish Receipt Looks Like. If you want copy-paste starter specs instead of drafting from scratch, read First-Task Prompt Templates. If you already use Aider for interactive work and want the clearest contrast, read Ralph Workflow vs Aider. If you want to inspect a public sample PROMPT.md, handoff notes, and review/fix artifacts before you run Ralph Workflow yourself, read Example Review Bundle. If you are comparing category options first, read Open-Source AI Coding Orchestrator: What Ralph Workflow Is Actually For. If you are comparing orchestration tools directly, read AI Agent Orchestration CLI: A Practical Comparison for Developers. If the missing piece is a spec-first mental model instead of a bigger prompt, read Spec-Driven AI Agent: Why the Spec Matters More Than the Prompt. Use the primary repo on Codeberg for inspection, stars, watches, and issues: https://codeberg.org/RalphWorkflow/Ralph-Workflow. The GitHub mirror is here if you already track projects there: https://github.com/Ralph-Workflow/Ralph-Workflow.

Before you start

You will need:

  • Python 3.12 or newer — check with python --version

  • A git repository — Ralph Workflow runs inside a git repo

  • At least one supported AI agent on your PATH — usually claude (Claude Code), Codex CLI, or opencode (OpenCode). If you want the documented non-interactive Claude path, configure claude-headless.

If you are unsure which one to start with, use the agent that is already installed, already authenticated, and already familiar, then read Which Agent Should I Start With?.

Install links:

Install in 60 seconds

pipx install ralph-workflow
ralph --version

If pipx is not available yet:

python -m pip install pipx
python -m pipx ensurepath

Your first run

1. Go to your git repository

cd /path/to/your/project

Most teams use Ralph Workflow in an existing repository they already care about. If you are trying it in a scratch repo instead, create one first:

git init my-project && cd my-project

2. Initialize Ralph Workflow

ralph --init

This creates PROMPT.md plus the project-local .agent/ support files Ralph Workflow needs to run.

If this repository also needs a project-local copy of the main Ralph Workflow config, create it explicitly:

ralph --init-local-config

3. Edit PROMPT.md

Open PROMPT.md and replace the example content with your actual task:

# Goal

Add a /health endpoint that returns HTTP 200 with {"status": "ok"}.

## Acceptance criteria

- GET /health returns HTTP 200
- Response body is valid JSON with status == ok
- A new test covers the endpoint

A strong first spec says:

  • what should change

  • what should stay untouched

  • what done looks like

  • what checks prove it worked

If a blank page slows you down, start from First-Task Prompt Templates and adapt the closest shape to your repo.

Important: remove the <!-- ralph:starter-prompt ... --> comment at the top. Ralph Workflow refuses to run while that sentinel is still present so you do not accidentally launch the placeholder task.

4. Verify the environment

ralph --diagnose

This is the recommended pre-flight check before the first real run. Fix any ❌ rows before continuing. Common issues:

  • No agent on PATH → install claude or opencode

  • Config errors → run ralph --regenerate-config

5. Start the run

ralph

Ralph Workflow shows progress inline while it runs. When it finishes, the result is in your repo — finished code you can review and merge.

How to judge the result honestly

Do not ask whether the agent looked smart.

Ask:

  • does the diff match the task?

  • are the changes small enough to review?

  • did the checks really run?

  • would I merge this?

That is the real product test.

If you want to see what a trustworthy handoff looks like before your first run, read What Good Ralph Workflow Output Looks Like.

If the run is promising or exposes useful friction, use After Your First Ralph Workflow Run to turn that private result into the right public Codeberg action.

In plain terms:

  • if the run earned trust, put the signal on the primary Codeberg repo first

  • if the run missed, file the exact first-run friction on Codeberg so the next run is easier to judge

What happens during a run

You do not need the full internal model to operate Ralph Workflow. The short version is:

  1. Planning — Ralph Workflow turns your task into a plan

  2. Development — an implementation agent works through the plan

  3. Verification — Ralph Workflow checks the result against your acceptance criteria and decides whether more work is needed

  4. Completion — the run ends with the resulting changes saved in the repo, ready for your judgment

If you later want the deeper mechanics — phases, drains, loopbacks, policy files, and artifact contracts — see Concepts and Configuration.

When something goes wrong

The sentinel comment is still in PROMPT.md

PolicyValidationError: PROMPT.md is still the starter template

Replace the example task and remove the <!-- ralph:starter-prompt ... --> line.

No agents found on PATH

ralph --diagnose

Install claude or opencode, then run the diagnostic again.

Config errors in ralph --diagnose

ralph --regenerate-config

This rewrites config files from the bundled defaults and keeps backups with a .bak suffix.

Next steps

If your first run gives you a clean diff, real checks, and a result you would merge, hand Ralph Workflow a bigger task the next night.