Skip to main content
Ralph Workflow
Free & Open Source First Run Guide

Your first autonomous coding run — tonight.

Ralph Workflow runs the AI coding agents you already use. Pick one real backlog item, write a short spec, run it overnight, and come back to something you can actually review.

Star on Codeberg → Install first
1

Pick the right first task

Your first Ralph Workflow run should be real but contained — a task you actually want done, not a toy. But don't start with something that spans 12 files and three services.

✅ Good first tasks

  • Add a CLI flag to an existing command
  • Write tests for an untested module (~5-10 functions)
  • Refactor one class to use a new pattern
  • Generate a data migration script
  • Add a new endpoint to an existing API

❌ Bad first tasks

  • "Add authentication" (too broad)
  • "Rewrite the database layer" (too risky)
  • "Improve performance" (unmeasurable)
  • Anything touching 20+ files at once
  • Tasks with no clear success criteria

The rule of thumb:

If you'd trust a mid-level engineer to do it in an afternoon with clear instructions, it's a good first Ralph Workflow task.

2

Write a one-paragraph spec

Ralph Workflow uses plan mode to decompose your spec into actionable steps. The spec is the contract — write it like you'd write a pull request description, not a novel.

Example spec (SPEC.md)

Goal: Add a --dry-run flag so ralph --dry-run prints what each phase would do without invoking any agents.

Scope: The CLI entrypoint and workflow runner. Do not modify agent invocation paths.

Behavior: When --dry-run is passed, Ralph Workflow should print each planned phase (planning, development, review, fix) and exit 0 without calling any agent CLI. Without the flag, behavior is unchanged.

Success: Running ralph --dry-run prints the phase plan and exits 0. Running ralph without the flag still runs the full workflow. Existing tests pass.

A good spec has four parts:

  1. Goal — one sentence saying what gets done
  2. Scope — which files/packages are in play, what's off-limits
  3. Behavior — what the agent should actually produce
  4. Success — how you'll judge the result (tests pass, manual check, etc.)
3

Install and run

Install Ralph Workflow, initialize it inside your repo, and kick off your first run. You need Python 3.12+ and at least one AI coding agent available on your machine.

pip install ralph-workflow       # install the CLI
cd your-project                   # go to a git repo
ralph --init                      # create .agent/ support files
ralph --diagnose                  # check agents are reachable
$EDITOR PROMPT.md                 # write your spec
ralph                             # start the unattended workflow

That's it. Ralph Workflow will plan, build, test, and fix — each phase hands off to the next. When it finishes, you get a reviewable result in your working directory.

💡 Pro tip: Run it before bed. Ralph Workflow is built for overnight work — start it at 10pm, wake up to a review at 7am. The checkpoint system means you won't lose progress if something goes sideways at 3am.

4

Judge the result honestly

This is the most important step. Don't just look at whether the tests pass — look at whether you'd actually merge this.

Your morning-after review checklist:

  1. ✓ Does it compile/run? If it doesn't start, the agent failed at the most basic level.
  2. ✓ Do existing tests still pass? If the agent broke something unrelated, it's a regression.
  3. ✓ Do new tests exist? The agent should have added tests for the new behavior — if it didn't, the spec wasn't followed.
  4. ✓ Is the code readable? If you can't understand what the agent wrote without reading every line three times, it's not merge-ready.
  5. ✓ Would you merge this? The ultimate question. If the answer is yes, your first Ralph Workflow run was a success.

If it worked

You just got real engineering done while you slept. Commit it, push it, and pick your next task. Each run makes Ralph Workflow's planning more accurate because it learns from what succeeded.

If it didn't

The most common first-run failure is a spec that's too vague. Tighten the scope, add a clearer success criterion, and try again. Ralph Workflow's checkpoint system means you can resume from the last good state — you don't start over.

Free. Open source. Runs tonight.

Ralph Workflow is on Codeberg. Star it, fork it, install it. Your first run is one spec file away.

Codeberg (primary) GitHub (mirror) Install →