---
slug: "rahulmutt-pi-ralph"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/rahulmutt/pi-ralph@main/README.md"
repo: "https://github.com/rahulmutt/pi-ralph"
source_file: "README.md"
branch: "main"
---
# @rahulmutt/pi-ralph

A [pi](https://github.com/badlogic/pi) extension that adds the `/ralph` command — a Ralph Wiggum loop that runs a prompt file repeatedly across fresh sessions.

## Install

```bash
pi install npm:@rahulmutt/pi-ralph
```

Or try it without installing:

```bash
pi -e npm:@rahulmutt/pi-ralph
```

## Usage

```text
/ralph <prompt-file>
/ralph [iterations] <prompt-file>
/ralph stop
```

### Examples

```text
/ralph prompts/implement.md
/ralph 5 prompts/implement.md
/ralph 2 "prompts/my prompt.md"
/ralph stop
```

### Behavior

- **iterations** is optional and defaults to `3` (max `1000`)
- `/ralph stop` requests a graceful stop: the current iteration is allowed to finish, and the loop exits before starting the next iteration
- Each iteration starts in a **fresh session** branched from the original, so context is cleared before the prompt runs
- Progress is persisted under `.ralph/`:
  - `.ralph/RALPH.md` is the always-current summary
  - `.ralph/<YYYY>/<MM>/<DD>/RALPH-<HH>-<MM>-<SS>-<mmm>.md` stores the full per-invocation progression, appending the last message from each iteration into the same file
  - `.ralph/<YYYY>/<MM>/<DD>/RALPH-<HH>-<MM>-<SS>-<mmm>-iter-<NNN>.jsonl` stores the transcript for each individual iteration, with all JSONL files from one `/ralph` run sharing the same invocation prefix
- Prompt files may live under the project directory, `~/.pi`, or `~/.local`
- Paths with spaces can be quoted

## How it works

The Ralph Wiggum loop:

1. Waits for the agent to become idle
2. Captures the current session as the parent
3. For each iteration:
   - Creates a new session (branched from the parent)
   - Sends the prompt file contents as a user message
   - Waits for the agent to finish
   - Appends the iteration's last assistant message into the current invocation's `RALPH-*.md`
   - Writes that iteration's transcript to its own `RALPH-*-iter-<NNN>.jsonl`

This is useful for running the same prompt (e.g., an implementation plan) repeatedly, where each iteration picks up the next uncompleted task from a plan file.

## License

MIT