Ralph Wiggum Extension

Long-running agent loops for iterative development. Best for long-running-tasks that are verifiable. Builds on Geoffrey Huntley's ralph-loop for Claude Code and adapts it for Pi. This one is cool because:

• You can ask Pi and it will set up and run the loop all by itself in-session. If you prefer, it can also invoke another Pi via tmux
• You can have multiple parallel loops at once in the same repo (unlike OG ralph-wiggum)
• You can ask Pi to self-reflect at regular intervals so it doesn't mindlessly grind through wrong instructions (optional)

Note: This is a flat version without subagents, similar to the Anthropic plugins implementation.

Install

pi install npm:@tmustier/pi-ralph-wiggum

pi install git:github.com/tmustier/pi-extensions

Then filter to just this extension in ~/.pi/agent/settings.json:

{
  "packages": [
    {
      "source": "git:github.com/tmustier/pi-extensions",
      "extensions": ["ralph-wiggum/index.ts"],
      "skills": ["ralph-wiggum/SKILL.md"]
    }
  ]
}

Recommended usage: just ask Pi

You ask Pi to set up a ralph-wiggum loop.

• Pi sets up .ralph/<name>.md with goals and a checklist (like a list of features to build, errors to check, or files to refactor)
• You let Pi know:
  1. What the task is and completion / tests to run
  2. How many items to process per iteration
  3. How often to commit
  4. (optionally) After how many items it should take a step back and self-reflect
• Pi runs ralph_start, beginning iteration 1.
  • It gets a prompt telling it to work on the task, update the task file, and call ralph_done when it finishes that iteration
  • When the iteration is done, it calls ralph_done, resending the same prompt*
• Pi runs until either:
  • All tasks are done (Pi sends <promise>COMPLETE</promise>)
  • Max iterations (default 50)
  • You hit esc (pausing the loop) If you hit esc, you can run /ralph-stop to clear the loop. Alternatively, just tell Pi to continue to keep going.

Commands

| Command | Description | |---------|-------------| | /ralph start <name\|path> | Start a new loop | | /ralph resume <name> | Resume a paused loop | | /ralph stop | Pause current loop | | /ralph-stop | Stop active loop (idle only) | | /ralph status | Show all loops | | /ralph list --archived | Show archived loops | | /ralph archive <name> | Move loop to archive | | /ralph clean [--all] | Clean completed loops | | /ralph cancel <name> | Delete a loop | | /ralph nuke [--yes] | Delete all .ralph data |

Options for start

| Option | Description | |--------|-------------| | --max-iterations N | Stop after N iterations (default 50) | | --items-per-iteration N | Suggest N items per turn (prompt hint) | | --reflect-every N | Reflect every N iterations |

Agent Tool

The agent can self-start loops using ralph_start:

ralph_start({
  name: "refactor-auth",
  taskContent: "# Task\n\n## Checklist\n- [ ] Item 1",
  maxIterations: 50,
  itemsPerIteration: 3,
  reflectEvery: 10
})

Credits

Based on Geoffrey Huntley's Ralph Wiggum approach for long-running agent tasks.

Changelog

See CHANGELOG.md.