ralph-harness

keep-on-ralphing

A reusable Ralph loop harness: drive an LLM coding agent through a task list one turn at a time, in a sandbox container, using the commit graph as the objective progress signal. Install it once, point it at any project.

Distilled from the Keep on the Borderlands build and generalized. Scope is deliberate: Linux + podman, single architecture, team-shared via GitHub. Not multi-arch, not macOS/Windows, not Docker-tested.

Three channels

The harness splits by where each piece runs:

   IN-CONTAINER            HOST-SIDE (Claude Code)        IN-REPO (data)
   ────────────            ──────────────────────         ──────────────
   the loop runner    →    /ralph-init      (scaffold)  →   ralph.conf  PROMPT.md
   (ralph.sh,              /ralph-status    (report)        tasks.md    STATUS.md
    until_reset.py)        /ralph-build-base (build img)    scripts/gate.sh + hook
   ⇒ base/ image          ⇒ skills/ (this plugin)         .github/workflows/ci.yml
                                                          specs/ tests/ decisions/
                                                          thin Containerfile + Makefile
                                                          ⇒ generated by /ralph-init

• base/ — the podman base image. It bakes ralph.sh + until_reset.py onto PATH, so a consuming project carries no machinery; its Containerfile just FROMs the base. One source of the runner → no drift.
• skills/ — the Claude Code plugin: /ralph-init scaffolds a project's config from templates/; /ralph-status reports loop state from .ralph/; /ralph-build-base builds ralph-base:v1 from the plugin's bundled base/ (clone-free).
• templates/ + example/ — the per-project config surface and a fully resolved sample.
• extras/ — unsupported odds and ends (see its README).

Use it on a project

Install the plugin (Claude Code):

/plugin marketplace add swinney/keep-on-ralphing
/plugin install ralph-harness@keep-on-ralphing

Build the base image once — no clone, it ships with the plugin:

/ralph-build-base    # builds ralph-base:v1 from the plugin's bundled base/ (registry-free)

The plugin bundles base/ + the Makefile, so the image builds straight from the install. Re-run /ralph-build-base after a /plugin update that touched the runner. (Contributors working from a keep-on-ralphing checkout can make build-base instead.)

In your project:

/ralph-init          # scaffolds config + an ENFORCED gate (scripts/gate.sh, a
                     # pre-commit hook, CI) + the specs/tests/decisions skeleton
make build           # your loop image, FROM ralph-base (also installs the gate hook)
make login           # one-time Claude Code auth
make loop            # run the loop (Ctrl-C to stop)   |  make loop-once for a single turn
/ralph-status        # check on it anytime

The loop stops when a turn writes a reason to STATUS.md, after RALPH_MAX_STALLS consecutive no-commit turns, or on Ctrl-C.

The scaffolded gate is enforced: scripts/gate.sh is the single source of the gate command, a pre-commit hook runs it and blocks red commits, and a CI workflow runs the same script. A red gate therefore yields no commit — which the loop counts as a stall — so broken work halts the loop for review instead of compounding. The gate also includes a coverage threshold (a global floor by default), so "tests pass" can't stand in for "the code is tested" — a supporting check alongside the review gate above.

The hook is installed via core.hooksPath (the Makefile hooks target), which is repo-wide: once set, it gates every commit, host or container. The gate runs where its toolchain lives — the container — so host-side committers need that toolchain locally or should commit via make shell.

Outer-loop review gate (opt-in)

The local gate above is the inner loop. There is also an outer loop (RALPH_REVIEW_GATE, on by default): after a committing turn the runner pushes the branch, opens/uses a PR, asks an independent reviewer (GitHub Copilot by default) to review it, and treats zero findings + green CI as the only PASS. Findings are written to review-findings.md, which the agent must resolve before any new task; persistent findings halt the loop for a human after RALPH_REVIEW_MAX_ROUNDS. RALPH_AUTO_MERGE (separate, default off) controls whether a clean PR auto-merges or is parked for you. All GitHub work is the runner's — the container agent never touches git/gh — so the gate works with any coding agent. Independent review catches the "wired-wrong but green" class that tests, types, and lint structurally cannot (the lesson the field log earned the hard way).