pi-ralph

A pi extension — iterative goal-achievement loop with Generator → Critique → Judge agents.

Install

pi install npm:@entelligentsia/pi-ralph

Or pin a version:

pi install npm:@entelligentsia/[email protected]

From GitHub:

pi install git:github.com:Entelligentsia/pi-ralph

What It Does

Give it a goal. It loops — generate, critique, judge — until the goal is met or iterations run out.

Each agent's system prompt is dynamically generated from the goal, so they're domain-aligned from the start. Output streams to chat as it happens — like tail -f.

Usage

/ralph-loop-anything --goal "Your goal here" --loop 5

• --goal (required): The goal to achieve
• --loop (optional, default 3): Maximum iterations

How It Works

1. Feasibility check  →  can an LLM do this?
2. Prompt generation   →  domain + agent prompts tailored to the goal
3. Loop (up to N):
   ├─ Generate   →  produces a result
   ├─ Critique   →  identifies problems, suggests improvements
   └─ Judge      →  { done: true/false, reason }
       └── if not done: feeds result + criticism back to Generator
4. Final message with verdict

Every step posts a message to chat as it completes. No hidden progress bars — you see each agent's output the moment it arrives.

LLM Calls Per Run

| Step | Calls | |------|-------| | Feasibility | 1 | | Prompt generation | 1 | | Per loop iteration | 3 (generate + critique + judge) |

Total for --loop 3: 1 + 1 + (3 × 3) = 11 LLM calls

Examples

Creative Writing

/ralph-loop-anything --goal "Write a complete short story in one sentence and fewer than 10 words that is better than Hemingway could write"

/ralph-loop-anything --goal "Write a villanelle poem about debugging at 3am"

/ralph-loop-anything --goal "Invent a new myth that explains why rivers bend, told as if by a 9th-century monk"

Code

/ralph-loop-anything --goal "Write an ergonomic CLI argument parser in Rust that handles flags, options, subcommands, and generates help text" --loop 5

/ralph-loop-anything --goal "Implement a lock-free concurrent hash map in Zig"

/ralph-loop-anything --goal "Write a single-file SQLite clone in C that supports CREATE TABLE, INSERT, and SELECT with WHERE clauses"

Design & Strategy

/ralph-loop-anything --goal "Design a go-to-market strategy for a developer tools startup that has a free CLI tool but wants to monetize a team tier"

/ralph-loop-anything --goal "Create a 12-week fitness program for a 40-year-old desk worker who has 30 minutes a day and bad knees"

/ralph-loop-anything --goal "Write a production-ready incident response playbook for a SaaS company experiencing a data breach"

Explaining & Teaching

/ralph-loop-anything --goal "Explain monads to a JavaScript developer who has never used Haskell, using only analogies from web development"

/ralph-loop-anything --goal "Create a 5-minute presentation script that explains neural networks to a room of skeptical middle managers"

Constraints & Style

/ralph-loop-anything --goal "Rewrite the Gettysburg Address as if it were a Slack announcement from a tech CEO" --loop 2

/ralph-loop-anything --goal "Write a recipe for coq au vin where every step is a haiku"

/ralph-loop-anything --goal "Explain quantum entanglement using only words with 4 letters or fewer"

Architecture

| File | Purpose | |------|---------| | index.ts | Thin entry point — parses args, calls orchestrator | | agents/orchestrator.ts | Coordinates full flow: feasibility, prompts, loop, verdict | | agents/generator.ts | Generator agent — produces or improves a result | | agents/critique.ts | Critique agent — evaluates result against the goal | | agents/judge.ts | Judge agent — decides if goal is achieved | | types.ts | Shared interfaces (LoopIteration, LoopStep, etc.) | | prompts.ts | Static system prompts (feasibility, prompt generator, fallbacks) | | helpers.ts | Text utilities (truncate, firstNLines) | | llm.ts | LLM client (oneshotLLM, parseJsonResponse) | | argParser.ts | Command argument parsing | | renderer.ts | Message renderer — passes markdown content through |