teknologist-plugins

⚠️ Work in Progress: This plugin is under active development. Expect bugs and breaking changes.

Installation

Install this plugin in Claude Code:

# First, add the marketplace (one-time setup)
/plugin marketplace add https://github.com/teknologist/claude-ralph-wiggum-pro.git

# Then install the plugin
/plugin install ralph-wiggum-pro@teknologist-plugins

---

Ralph Wiggum Pro

Implementation of the Ralph Wiggum technique for iterative, self-referential AI development loops in Claude Code.

Based on: This is a fork of the official ralph-wiggum plugin from Anthropic. Huge thanks to Anthropic for the original plugin and to Geoffrey Huntley for coining the Ralph Wiggum technique. See Enhancements below for additions made in this fork.

Enhancements in This Fork

This fork adds the following features on top of the original Anthropic plugin:

v2.2.x - Robust Multi-Session Architecture (Latest)

Core Architecture:

• Global Directory Consolidation: All Ralph data stored under ~/.claude/ralph-wiggum-pro/:
  • loops/ - State files for active loops
  • logs/ - Session logs (sessions.jsonl, debug.log)
  • sessions/ - PPID session tracking files
  • transcripts/ - Iteration and full transcript files
• PPID-Based Session Tracking: Reliable session identification using process tree walking:
  • Session ID stored in ppid_$PID.id files (keyed by Claude Code's PID)
  • Survives /clear commands within the same terminal
  • Automatically synchronized when Claude Code regenerates session IDs internally
• Simplified State Management: File existence = active loop (no more active field in frontmatter)
• Automatic Cleanup: SessionEnd hook removes state files when terminal closes

Session ID Synchronization (v2.2.9):

• Stop hook walks process tree to find existing PPID file
• Updates PPID file with current session ID when mismatch detected
• Ensures subsequent loops in the same session work correctly
• Uses atomic writes (mktemp + mv) for safe concurrent access

Transcript System (v2.1.x):

• Iteration-by-iteration output capture
• Timeline view with collapsible iterations in dashboard
• Full transcript modal with search functionality
• Export transcripts as Markdown

Checklist System (v2.1.1):

• Task and acceptance criteria tracking
• Progress display in dashboard and /ralph-wiggum-pro:ralph-stats
• Checklist summary in each iteration's system message

v2.0.x - Dashboard & Session Logging

• Ralph Dashboard: Web-based dashboard for monitoring and managing Ralph loops
  • View all active and archived loops in real-time
  • Cancel active loops directly from the browser
  • Track statistics: success rates, durations, iteration counts
  • Run with bunx ralph-dashboard or npx ralph-dashboard
  • Configurable port (--port) and host (--host 0.0.0.0 for public access)
• Session Logging: All loops logged to ~/.claude/ralph-wiggum-pro/logs/sessions.jsonl
• /ralph-wiggum-pro:ralph-stats Command: View historical loop data with filtering by project, outcome, or count
• Active Loop Tracking: Loops logged when they start (not just when complete)
• Remote Cancellation: Cancel loops from dashboard
• Atomic Writes: All file operations use mktemp + mv pattern

v1.1.0 - Session Isolation

• Multi-Session Support: Multiple Claude Code terminals can run independent Ralph loops
• Session-Scoped State Files: Each session gets isolated state files
• Confirmation Prompts: /ralph-wiggum-pro:cancel-ralph asks for confirmation before cancelling
• Comprehensive Test Suite: Tests for session isolation, state file parsing, security validation

---

Features

• Session Isolation: Multiple Claude Code terminals can run independent Ralph loops on the same project
• Progress Tracking: Elapsed time display and iteration counting
• File-based Prompts: Load complex prompts from markdown files with --prompt-file
• Loop Management: List all active loops with /ralph-wiggum-pro:list-ralph-loops, cancel specific loops with /ralph-wiggum-pro:cancel-ralph
• Session Logging: All loop sessions are logged to ~/.claude/ralph-wiggum-pro/logs/sessions.jsonl with structured JSON data
• Session Stats: View historical loop data with /ralph-wiggum-pro:ralph-stats - filter by project, outcome, or time range

What is Ralph?

Ralph is a development methodology based on continuous AI agent loops. As Geoffrey Huntley describes it: "Ralph is a Bash loop" - a simple while true that repeatedly feeds an AI agent a prompt file, allowing it to iteratively improve its work until completion.

The technique is named after Ralph Wiggum from The Simpsons, embodying the philosophy of persistent iteration despite setbacks.

Core Concept