@rahulmutt/pi-ralph

A pi extension that adds the /ralph command — a Ralph Wiggum loop that runs a prompt file repeatedly across fresh sessions.

Install

pi install npm:@rahulmutt/pi-ralph

Or try it without installing:

pi -e npm:@rahulmutt/pi-ralph

Usage

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

Examples

/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