ralphkit 0.1.0

Iterative work/review loop for Claude Code

ralphkit

An iterative work/review loop for Claude Code. One model does the work, a different model reviews it. The loop continues until the reviewer says SHIP or max iterations are reached.

Inspired by Goose's Ralph pattern.

Install

pip install ralphkit

With uv:

uv tool install ralphkit

Or run directly without installing:

uvx ralphkit ralph-loop "your task here"

Quick Start

ralph-loop "Create a Python function in prime.py that checks if a number is prime. Include unit tests."

Usage

ralph-loop TASK [--config PATH] [--worker-model MODEL] [--reviewer-model MODEL] [--max-iterations N] [-y]

Arguments:

Argument	Description	Default
TASK	Task description (string or path to .md file)	required
--config PATH	Load settings from a YAML config file	none
--worker-model	Model for the work phase	opus
--reviewer-model	Model for the review phase	sonnet
--max-iterations	Max work/review cycles	10
-y / --yes	Skip confirmation prompt	off

Examples:

# Inline task
ralph-loop "Build a REST API"

# Task from a markdown file
ralph-loop task.md

# Override models
ralph-loop "Build a REST API" --worker-model sonnet --reviewer-model haiku

# Use a config file for shared settings
ralph-loop "Build a REST API" --config ralph.yaml

# Skip confirmation
ralph-loop "Build a REST API" -y

Config file

A config file is optional. When provided via --config, its values serve as defaults that CLI args can override.

# ralph.yaml
worker_model: opus
reviewer_model: sonnet
max_iterations: 10

Resolution order: built-in defaults → config file → CLI args.

How It Works

┌─────────────────────────────────────────┐
│  1. Read task                           │
│  2. Worker model does the work          │ ◄─── iteration N
│  3. Reviewer model reviews it           │
│  4. SHIP? -> done. REVISE? -> loop.     │
└─────────────────────────────────────────┘

Each iteration:

1. Work phase — the worker model reads the task (and any prior review feedback), writes code, runs tests, and summarizes what it did.
2. Review phase — the reviewer model examines all files, runs tests, and writes either SHIP (approve) or REVISE (with feedback).
3. If REVISE, the feedback is passed to the next iteration. If SHIP, the loop exits successfully.

State Files

State is persisted in .ralphkit/ in the current working directory so each stateless claude -p invocation can pick up where the last left off.

File	Purpose
task.md	The task description
iteration.txt	Current iteration number
work-summary.txt	What the worker did this iteration
work-complete.txt	Created when the worker thinks it's done
review-result.txt	SHIP or REVISE
review-feedback.txt	Specific feedback from the reviewer

Requirements

• Claude Code CLI (claude must be on your PATH)
• Python 3.10+