quick-ralph

Minimal Ralph-loop harness on top of either claude (Claude Code) or codex (OpenAI Codex CLI), both via OAuth. Three roles: Planner / Executor / Verifier. Fresh context per iteration; state persists to state/ on disk between iterations.

Run

Pre-requisites: claude and codex already logged in via OAuth. ANTHROPIC_API_KEY / OPENAI_API_KEY are unset by the harness defensively but the underlying CLIs must have stored credentials. The cwd must be a git repo with an origin remote (or pass --no-push).

quick-ralph --provider claude
# or
quick-ralph --provider codex

On start, quick-ralph asks for the goal by launching $VISUAL / $EDITOR (or vi / notepad). If state/GOAL.md already exists in the cwd, its contents pre-fill the editor — edit and save to use as the run's goal. Then quick-ralph creates a sibling git worktree (<parent>/<repo>-quick-ralph-<YYYYMMDD-HHMMSS>) on a fresh branch (quick-ralph/<stamp>), writes the goal to state/GOAL.md inside the worktree (always overwrites), and runs the loop inside the worktree. Every per-iter commit is also pushed to origin/<branch>. The original checkout is never modified.

Goal input (mutually exclusive; editor is the default):

• -m, --goal-message <text> — inline goal text
• -F, --goal-file <path> — read goal from a file (use -F - for stdin)
• (default) — launch the editor as described above

Non-interactive use (CI, scripts, piping) must pass one of the flags above; quick-ralph will not silently consume stdin or fall back to a file. An empty goal aborts the run.

Other flags: --provider claude|codex (default claude), --max-iters N (default 300), --model <m>, --no-push (skip remote push; still creates worktree+branch locally).

Termination: any of (a) state/STOP file present, (b) Planner emits <verdict>done</verdict>, (c) stall detector cap reached (3 consecutive fails on the same picked leaf → state/ESCALATE.md and non-zero exit), (d) --max-iters reached.

Design

Three roles:

• Planner — owns state/STATE.md, a single markdown task queue with three leaf states (- [ ], - [x], - [!] rejected: <reason>). Seeds the queue from state/GOAL.md on cold start; revises it each iter based on the prior verifier's output; picks one open leaf and writes its title to state/plan.md.
• Executor — implements the leaf in state/plan.md. Touches workspace files only, never state/.
• Verifier — runs after the executor and after a deterministic verify.sh (user-provided; replace per project). Emits <verdict>pass</verdict> or <verdict>fail</verdict> with gap bullets. Read-only access.

AGENTS.md at the worktree root is read by every role when present — put your product context there (build commands, file layout, conventions).

Fresh provider context per role per iteration; only the files under state/ and the worktree carry across.

Install

npm install -g @quick-start-soft/quick-ralph
quick-ralph --provider claude