Metadata-Version: 2.4
Name: ralphify
Version: 0.1.5
Summary: Harness toolkit for autonomous AI coding loops
Project-URL: Documentation, https://computerlovetech.github.io/ralphify/
Project-URL: Repository, https://github.com/computerlovetech/ralphify
Project-URL: Issues, https://github.com/computerlovetech/ralphify/issues
License-Expression: MIT
License-File: LICENSE
Keywords: agent,ai,autonomous,cli,coding,loop
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.11
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.9
Provides-Extra: ui
Requires-Dist: aiosqlite>=0.20; extra == 'ui'
Requires-Dist: fastapi>=0.110; extra == 'ui'
Requires-Dist: uvicorn[standard]>=0.29; extra == 'ui'
Requires-Dist: websockets>=12.0; extra == 'ui'
Description-Content-Type: text/markdown

<p align="center">
  <img src="cli-graphic.png" alt="ralphify" />
</p>

<p align="center">
  <a href="https://pypi.org/project/ralphify/"><img src="https://img.shields.io/pypi/v/ralphify?color=blue" alt="PyPI version"></a>
  <a href="https://pypi.org/project/ralphify/"><img src="https://img.shields.io/pypi/pyversions/ralphify" alt="Python versions"></a>
  <a href="https://github.com/computerlovetech/ralphify/blob/main/LICENSE"><img src="https://img.shields.io/github/license/computerlovetech/ralphify" alt="License"></a>
  <a href="https://computerlovetech.github.io/ralphify/"><img src="https://img.shields.io/badge/docs-computerlovetech.github.io%2Fralphify-blue" alt="Documentation"></a>
</p>

Put your AI coding agent in a `while True` loop and let it ship.

Ralphify is a minimal harness for running autonomous AI coding loops, inspired by the [Ralph Wiggum technique](https://ghuntley.com/ralph/). The idea is simple: pipe a prompt to an AI coding agent, let it do one thing, commit, and repeat. Forever. Until you hit Ctrl+C.

```
while :; do cat PROMPT.md | claude -p ; done
```

Ralphify wraps this pattern into a proper tool with config, iteration tracking, and clean shutdown.

## Install

```bash
uv tool install ralphify    # recommended
```

Or if you don't have `uv`:

```bash
pipx install ralphify       # isolated install via pipx
pip install ralphify         # plain pip (use a virtualenv or --user)
```

Any of these gives you the `ralph` command.

## Quickstart

```bash
# In your project directory
ralph init      # Creates ralph.toml + PROMPT.md
ralph run       # Starts the loop (Ctrl+C to stop)
```

That's it. Two commands.

Or skip setup entirely with an ad-hoc prompt:

```bash
ralph run -n 1 -p "Add type hints to all public functions in src/"
```

### What `ralph init` creates

**`ralph.toml`** — tells ralphify what command to run:

```toml
[agent]
command = "claude"
args = ["-p", "--dangerously-skip-permissions"]
prompt = "PROMPT.md"
```

**`PROMPT.md`** — a starter prompt template. This file IS the prompt. It gets piped directly to your agent each iteration. Edit it to fit your project.

### What `ralph run` does

Reads the prompt, pipes it to the agent, waits for it to finish, then does it again. Each iteration gets a fresh context window. Progress lives in the code and in git.

```bash
ralph run          # Run forever
ralph run -n 10    # Run 10 iterations then stop
ralph run -p "Fix the login bug"   # Ad-hoc prompt, no PROMPT.md needed
```

## The technique

The Ralph Wiggum technique works because:

- **One thing per loop.** The agent picks the most important task, implements it, tests it, and commits. Then the next iteration starts fresh.
- **Fresh context every time.** No context window bloat. Each loop starts clean and reads the current state of the codebase.
- **Progress lives in git.** Code, commits, and a plan file are the only state that persists between iterations. If something goes wrong, `git reset --hard` and run more loops.
- **The prompt is a tuning knob.** When the agent does something dumb, you add a sign. Like telling Ralph not to jump off the slide — you add "SLIDE DOWN, DON'T JUMP" to the prompt.

Read the full writeup: [Ralph Wiggum as a "software engineer"](https://ghuntley.com/ralph/)

## Beyond the basic loop

The simple loop works, but ralphify's real power comes from three primitives that live in the `.ralph/` directory.

### Checks — the self-healing loop

Checks validate the agent's work after each iteration. When one fails, its output automatically feeds into the next iteration so the agent can fix its own mistakes.

```bash
ralph new check tests
```

Edit `.ralph/checks/tests/CHECK.md`:

```markdown
---
command: uv run pytest -x
timeout: 120
---
Fix all failing tests. Do not skip or delete tests.
```

Now the loop self-corrects:

```
Iteration 1 → Agent adds feature → tests pass ✓ → moves on
Iteration 2 → Agent adds feature → tests fail ✗
Iteration 3 → Agent sees failure output → fixes tests → pass ✓
```

You define what "valid" means. Ralphify feeds failures back automatically.

### Contexts — dynamic data injection

Contexts inject fresh data into the prompt each iteration — git history, test status, anything a shell command can produce.

```bash
ralph new context git-log
```

Edit `.ralph/contexts/git-log/CONTEXT.md`:

```markdown
---
command: git log --oneline -10
---
## Recent commits
```

The command runs before each iteration. Use `{{ contexts.git-log }}` in your `PROMPT.md` to control where the output appears.

### Instructions — reusable rules

Instructions are static text blocks (coding standards, commit conventions) you can toggle on and off without editing the prompt.

```bash
ralph new instruction code-style
```

Drop `{{ instructions }}` into `PROMPT.md` to inject all enabled instructions.

## Customizing your prompt

The generated `PROMPT.md` is a starting point. A good prompt for autonomous loops typically includes:

- What to work on (specs, plan file, TODO list)
- Constraints — what NOT to do (no placeholders, no skipping tests)
- Process — how to validate and commit

The agent reads this prompt fresh every iteration, so you can edit it while the loop is running. When the agent does something dumb, add a sign to the prompt — the next iteration follows the new rules.

## Documentation

Full documentation at **[computerlovetech.github.io/ralphify](https://computerlovetech.github.io/ralphify/)** — tutorials, cookbook, prompt writing guide, and troubleshooting.

## Requirements

- Python 3.11+
- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (or any agent CLI that accepts piped input)

## License

MIT
