Ralph Kit

Ralph as a kit: kickoff → plan → build

Build in loops. Ship with backpressure.

Ralph Kit is a portable implementation + augmentation of Geoff Huntley’s Ralph methodology. It adds a repeatable kickoff flow for new projects, multi-model routing, and one-command GCP provisioning so you can run full-auto safely in a dedicated VM.

Get started Provision a runner Read the Playbook

What it adds

The classic Ralph loop is tiny: while :; do cat PROMPT.md | claude; done. Ralph Kit keeps the simplicity, but adds the missing ergonomics and guardrails you actually want in a repo.

plan-work multi-model routing GCP provisioner kickoff prompt .ralph runtime

Quick install

Install the kit into any repo (writes docs + prompts + a wrapper), then run planning/build loops.

./install.sh /path/to/target-repo --wrapper
cd /path/to/target-repo
./ralph.sh plan 1
./ralph.sh build 10

How it works

Ralph is a funnel: kickoff (optional, for greenfield) → planning (specs → plan) → building (plan → code + tests). Ralph Kit makes this repeatable.

Kickoff (new projects)

Use a memory-backed agent (ChatGPT/Claude Projects, long-running agent, etc.) to write high-quality docs/* + specs/* as a patch. Ralph consumes those.

Plan (specs → checklist)

Planning mode does gap analysis: compare specs to code, then update IMPLEMENTATION_PLAN.md with prioritized tasks + required tests.

Build (tasks → code + backpressure)

Building mode picks the top task, searches first (don’t assume), implements with tests, and updates plan/status/changelog.

Full-auto ≠ reckless: in auto-permissions mode, the agent can run arbitrary commands. Run in a dedicated VM/container. Treat the environment as disposable. See docs/sandboxing.md.

What gets added to your repo

Ralph steers by signs: prompts, operational notes, patterns in your codebase, and backpressure from tests/typecheck/lint. This kit drops in the structure so the signs are consistent.

File layout

Installer writes prompts + coordination files at repo root, and vendors the kit at ./ralph.

./
├─ AGENTS.md
├─ PROMPT_plan.md
├─ PROMPT_plan_work.md
├─ PROMPT_build.md
├─ IMPLEMENTATION_PLAN.md
├─ REQUESTS.md
├─ QUESTIONS.md
├─ STATUS.md
├─ CHANGELOG.md
├─ specs/
│  ├─ feature_template.md
│  └─ ...
├─ docs/
│  ├─ README.md
│  └─ ...
└─ ralph/
   ├─ bin/loop.sh
   ├─ bin/ralph-daemon.sh
   ├─ bin/kickoff.sh
   ├─ config.sh
   └─ ...

Routing + knobs

Works with Codex and/or Claude. By default: Codex plans/reviews, Claude builds. Override via env.

AI_MODEL=claude|codex force one model
RALPH_AUTOPUSH=false by default
RALPH_TEST_CMD run after review auto-fixes
RALPH_DEPLOY_CMD used by daemon on [DEPLOY]
CODEX_PLANNING_CONFIG / CODEX_REVIEW_CONFIG reasoning tuning

Tune it like a guitar: if Ralph is producing the wrong shape of code, don’t only tweak prompts — add better utilities/patterns and strengthen backpressure. The repo itself becomes the steering wheel.

How to use it

Two common paths: start a new repo from scratch (kickoff + plan + build), or augment an existing repo (specs + plan + build).

New project (greenfield)

Install kit + wrapper:

./install.sh /path/to/your/new-repo --wrapper
cd /path/to/your/new-repo

Generate a kickoff prompt (paste into your memory-backed agent):
```
./ralph.sh kickoff "<one paragraph project brief>"
```
Apply the patch your memory-backed agent returns (creates docs/*, specs/*, and a solid plan). Then run:
```
./ralph.sh plan 1
./ralph.sh build 10
```

Read the full kickoff workflow: docs/kickoff.md

Existing repo (augmentation)

Install kit + wrapper:

./install.sh /path/to/existing-repo --wrapper
cd /path/to/existing-repo

Write/curate specs for the system you want (3–8 files is a great start). Then run planning:
```
./ralph.sh plan 1
```
Build in loops with backpressure:
```
./ralph.sh build 10
```

Tip: use plan-work on a work branch when you want a scoped plan: ./ralph/bin/loop.sh plan-work "scope"

Provision a Ralph-equipped VM (GCP)

The whole point: run full-auto without giving an agent access to your personal machine. Provision a dedicated runner VM, then clone your repo and loop.

One command

Requires gcloud on your laptop. Uploads the kit to the VM, installs Node/pnpm + agent CLIs (best-effort), and stores keys in /etc/ralph/keys.env.

OPENAI_API_KEY=... ANTHROPIC_API_KEY=... \
  ops/gcp/provision.sh --name ralph-runner --project <gcp-project> --zone us-central1-a

Security: treat runners as disposable. Use least-privilege tokens. Never put personal SSH keys or browser cookies on the VM.

After it’s up

SSH in, clone your target repo, install the kit, and run loops in tmux.

gcloud compute ssh ralph-runner --project <gcp-project> --zone us-central1-a

mkdir -p ~/work && cd ~/work
git clone <your-repo-url> repo
/opt/ralph-kit/install.sh ~/work/repo --wrapper

cd ~/work/repo
./ralph.sh plan 1
./ralph.sh build 10

More details: ops/gcp/README.md and docs/sandboxing.md