Ralph-ing easy and safe: ralph-workflow

Ralph is a deceptively simple pattern: put one prompt in a while loop and let a coding agent hammer on a backlog until every story passes.

It is not clever but persistent, especially exploratory projects, prototypes experiments, it is weirdly effective.

The catch: Ralph idea rely on running your agent with --dangerously-skip-permissions (or --yolo, or --yes, depending on CLI). That is the whole point, no human in the loop.

But if you run it on your laptop, the agent inherits everything your shell can reach: every SSH key, every cloud credential, every private repo. A single bad tool call or prompt injection and your workstation is the blast radius.

ralph-workflow is a small CLI that help you scaffolds a Ralph project, that includes wrap VS Code Dev Container with credentials isolated from the host. One command:

npx ralph-workflow

What you get

The interactive flow asks four questions — which coding CLI (Claude Code, Codex, Gemini, OpenCode), whether to set up a Dev Container, which base image, and whether to mint a scoped GitHub PAT — and then drops three things into your repo:

1. A .devcontainer/ config with the credential-forwarding env vars explicitly blanked out. VS Code's git auth helpers are disabled inside the container. Your host keychain stays on your host.

2. A single-repo fine-grained PAT (if you want one), written to .ralph/token, gitignored. The token is scoped to this repo. if Ralph goes off the rails, it cannot touch your other private repos while maintaining access to github work it needs to work on.

3. A scripts/ralph/ directory containing the loop itself: ralph.sh, a prompt.md template, a prd.yaml backlog, and a progress.txt log. The simple package to kickstart your ralph loop

To put it simple on how ralph works, The prompt.md tells the model to pick the highest-priority story from prd.yaml, implement exactly one, run typecheck + tests, commit, and stop. The bash loop re-invokes it for the next story. When every story has passes: true, the model replies <promise>COMPLETE</promise> and the loop exits.

The discipline is in the prompt, not the orchestration. One story per invocation, saving code assistant from bloating the context window. Every change committed together with the updated prd.yaml and an appended progress.txt learning. The loop is trivially resumable kill it, restart it, and it picks up where the git history left off.

Why the Dev Container actually matters

The temptation is to skip the container because "my Dockerfile is fine" or "I trust the agent." The problem is not that you distrust the model — the problem is that the model executes tool calls against whatever shell it is given.

Try it

mkdir my-ralph-experiment && cd my-ralph-experiment
git init
npx ralph-workflow

Answer the prompts, open the folder in VS Code, "Reopen in Container," then:

Fill out prd.yaml with the stories you want.

then start:

cd scripts/ralph
./ralph.sh 20   # run up to 20 iterations

Walk away. Come back to a git log.

Ralph is clueless. Ralph is persistent. That turns out to be most of what you need.

---

Source: github.com/rickvian/ralph-workflow · Docs: rickvian.github.io/ralph-workflow