Why Worktrees Are Not Enough for Autonomous Coding¶
If you already use Claude Code, Codex or similar tools with git worktrees, you have solved part of the problem. You have not solved how the work gets onto main.
Ralph Workflow is a free, open-source command-line tool that lands coding-agent work directly on main, automatically, with no pull requests. It runs the coding-agent CLI you already use, on your own machine.
What worktrees are good at¶
Worktrees are genuinely useful. They help with:
separating concurrent coding tasks
avoiding checkout thrash
reducing file collisions between sessions
making branch-per-task work less painful
If your problem is “my coding sessions keep stepping on each other,” worktrees help.
What worktrees do not solve¶
A worktree is isolation. It ends with a branch. Someone still has to get that branch onto main.
In the usual setup, each branch becomes a pull request, and a person reads the diff and merges it. With agents, that breaks down:
The review comes at the wrong moment. By the time someone reads the diff,
mainhas moved. The review doesn’t survive the rebase, and CI on a stale base says nothing about the commit that lands.It is the wrong layer. Much rejected agent work is wrong about intent, not code quality. Reading the diff happens after the expensive mistake.
There is too much of it. Nobody can carefully read everything agents produce. Reviewers rubber-stamp it or become the queue.
More worktrees means more branches waiting in that queue.
The missing layer¶
The missing layer is not more isolation. It is a way for work to reach main that keeps up with main:
Approve the intent, not the diff. A spec that says what done means and how to check it, written before the code.
Integrate every commit onto current
main. No long-lived branches.Prove the exact commit that lands. Run the suite and acceptance checks on that commit, before the push.
Push it. No pull request, no person merging.
Where Ralph Workflow stands on each¶
Intent: partly today. You write the spec in
PROMPT.md.ralph --initcreates a starter file with a marker at the top, and Ralph Workflow refuses to run until you delete the marker. Nothing records an approval yet.Integration: works today. After each commit, Ralph Workflow rebases it onto your local
main; the agent resolves conflicts. If it can’t, the engine falls back to a merge commit.Proving the exact commit: not built. Today the push runs without checks. The agent is asked to run the checks in
PROMPT.md, but nothing enforces them, and its own review pass runs after the push. Your CI runs afterwards, onmain. The gate will run your suite on the exact commit before every push. It is the top engineering priority and has not shipped.Push: works today. Ralph Workflow pushes the whole local
maintoorigin/main. A plain push, never forced. Iforigin/mainmoved first, the push fails and the work rebases again.
Because the gate has not shipped, no push is verified today. Start on a repository where a bad commit costs one git revert.
The practical rule¶
Use worktrees when you need sessions isolated from each other on one machine.
Use Ralph Workflow when you want the agent’s work on main without a pull request in between, and you can watch what lands until the gate ships.
A first test:
Pick one real task in a repository that already has tests.
Describe it in
PROMPT.md: the outcome, the checks, what is out of scope.Run
ralph.Check what landed on
mainagainst the spec, andgit revertanything that is wrong.
Next steps¶
Start with Getting Started
Read When Unattended Coding Fits to choose a good first task
Read How to check what landed on main for what to look at after a run