Metadata-Version: 2.4
Name: ralphkit
Version: 0.1.0
Summary: Iterative work/review loop for Claude Code
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# ralphkit

An iterative work/review loop for [Claude Code](https://docs.anthropic.com/en/docs/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](https://block.github.io/goose/docs/tutorials/ralph-loop).

## Install

```bash
pip install ralphkit
```

With [uv](https://docs.astral.sh/uv/):

```bash
uv tool install ralphkit
```

Or run directly without installing:

```bash
uvx ralphkit ralph-loop "your task here"
```

## Quick Start

```bash
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:**

```bash
# 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.

```yaml
# 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](https://docs.anthropic.com/en/docs/claude-code) (`claude` must be on your PATH)
- Python 3.10+
