Introducing Ralph Workflow

The artifact I want from an unattended coding run is not a transcript. It is a diff I can review without feeling like I need to reconstruct the whole night in reverse. That sounds obvious, but it is exactly where most AI coding tools get flimsy. The model can write code, often very good code. The weak part is everything around the code: the planning, the retries, the verification, the moments where the run should stop, and the moments where it should loop again. Too often you come back to a giant diff, a confident summary, and the uneasy sense that you now have to audit the agent's entire thought process just to decide whether it helped.

That is the problem I wanted Ralph Workflow to solve. Not “autonomous software engineering,” and not a theatrical demo where an agent appears to replace the team. Something much more useful than that. I wanted a way to hand an AI coding agent a scoped task, let it keep working without constant steering, and come back to something sturdier than vibes.

The bottleneck is not code generation anymore

This is the part that has changed fastest over the last year. For a lot of real tasks, the model is no longer the weakest link. The weakest link is everything around it.

Did it make a sensible plan before editing? Did it keep the work inside scope? Did it run the checks that actually matter for the repo? Did it notice when those checks failed? Did it retry intelligently, or just dig the hole deeper? Did it stop for a good reason, or because it got tired and wrote a convincing paragraph?

That is the loop people still end up doing by hand. You are not just prompting the agent. You are acting as planner, reviewer, verifier, and recovery system. That works when you are sitting right there. It does not work when the task takes two hours and you would prefer to spend those two hours doing something else.

Ralph was the seed, not the finished thing

The original Ralph idea is simple and still good: run the agent again in a fresh context, let the filesystem carry the state forward, and keep the model out of the fog that builds up in long chat sessions.

That part matters more than it sounds like it should. Context degradation is real. Long sessions accumulate junk: failed attempts, stale assumptions, tool noise, partial fixes, and local detours that slowly become the new direction. A fresh pass is often a better pass.

But a raw loop is still just a loop. It does not know whether the plan is weak, whether the diff is reviewable, or whether a failure means “retry,” “switch agents,” “resume later,” or “a human actually needs to look at this now.” Ralph Workflow is the part that adds structure around that idea.

That is the part I most want the pitch to get right. The point is not that Ralph Workflow replaces the simple Ralph loop with something more elaborate. The point is that the loop is simple enough to trust, reason about, and run again tomorrow. The orchestration layer matters because it keeps that core loop intact while making the surrounding process repeatable, restartable, and easier to audit.

The workflow has to do the missing human job

The thing I keep coming back to is that unattended coding is not mostly about getting the agent to keep typing while you are gone. It is about making the hidden human loop explicit.

An actual run needs a few things the average prompt does not provide. It needs a durable task contract in PROMPT.md. It needs a planning pass that has to earn the handoff into implementation. It needs analysis gates that can loop weak work back instead of letting it drift forward. It needs verification based on the repo’s real checks, recovery when an agent flakes or a provider rate-limits, and a handoff that looks like commits, logs, artifacts, and a diff a human can actually review. That is the difference between “the agent ran” and “the workflow worked.”

Ralph Workflow is the outer loop

Ralph Workflow is the operating system for autonomous coding — a free and open-source tool that runs on your own machine. The workflow lives in the repo, where the team can inspect it, change it, and run it again tomorrow.

You write a scoped task. The system plans, analyzes, develops, reviews, and loops. Weak passes go back through analysis instead of quietly becoming the next state of the world. Successful passes leave behind git history and structured artifacts so the run is inspectable after the fact.

That last part matters to me a lot. I do not want an unattended coding tool that ends by saying “trust me.” I want one that ends with enough evidence that I do not have to.

Reviewable handoff beats a clever transcript

One of the quiet problems with prompt-first agent tools is that the handoff is usually conversational. You get a transcript, maybe a summary, maybe a list of what the model thinks it did. That is useful, but it is not the same as engineering evidence.

Ralph Workflow is built around a different idea: the handoff should be repo-native. The output should not be just a chat log. It should be the plan, the review, the verification output, the artifacts, the commit trail, and the final diff. You should be able to inspect why the run stopped where it stopped, whether the work stayed aligned with the spec, and whether the result is something you would actually merge.

Vendor-neutral is not a slogan here

Another reason this project exists is that no single model vendor is going to build the orchestration layer I actually want. Anthropic is not going to ship “use Codex for review.” OpenAI is not going to ship “use Claude for planning.” No vendor is especially motivated to help you route work to a competitor when that competitor is better or cheaper for a particular phase.

So Ralph Workflow does not assume one model, one provider, or one CLI is the whole answer. Planning, implementation, review, and fix work are different jobs. Sometimes they deserve different agents. Sometimes they deserve different price points. Sometimes the best practical improvement is not “find a smarter model,” but “stop paying frontier rates for grunt work.” That is why model routing lives in config, inside the repo, where the team can actually own it.

Recovery is part of the product, not an afterthought

The fantasy version of unattended coding is simple: start the run, go to sleep, wake up, done. The real version is messier.

Networks fail. Providers rate-limit. Agents get stuck. Good plans still lead to weak diffs. A run can be valuable and still need a second pass. If your whole strategy is one giant prompt and a prayer, every interruption feels like starting over.

Ralph Workflow treats recovery as normal engineering, not an embarrassment. Checkpoints, resume behavior, retry budgets, fallback chains, and failure classification are part of the point. That is not flashy marketing copy, but it is the kind of thing that decides whether a tool is useful on a Tuesday night when the run fails at 2 a.m.

Start with something boring

The best first task is not “build the product.” It is something boring and bounded.

Add tests to an existing module. Fix a batch of lint or type-check failures. Refactor one narrow subsystem. Update docs from code. Migrate one internal API that already has clear edges. Those are the tasks where unattended workflow either proves itself or exposes its real failure modes.

That is what I want from a first run: not a magic trick, but signal.

The pitch, as I see it

If I had to compress the point of Ralph Workflow into one sentence, it would be this: it is a way to turn capable AI coding agents into unattended runs you can actually review, not because the models became perfect, but because the workflow got stricter.

Getting started

Install Ralph Workflow:

pipx install ralph-workflow

Initialize it in your repo:

ralph --init

Write the task in PROMPT.md, then run:

ralph

Start with a small, scoped task. Read the artifacts. Read the diff. See whether the workflow catches the kinds of mistakes you are tired of catching yourself.

That is the standard I care about: not whether the agent looked impressive for ten minutes, but whether you can walk away, come back later, and find work that still looks sane in daylight.