@sureshsankaran/ralph-wiggum 0.1.0

package/README.md

@@ -0,0 +1,243 @@
+# Ralph Wiggum Plugin
+
+Implementation of the Ralph Wiggum technique for iterative, self-referential AI development loops in OpenCode.
+
+## 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
+
+This plugin implements Ralph using a **session.idle hook** that intercepts session completion:
+
+```bash
+# You run ONCE:
+/ralph-loop "Your task description" --completion-promise "DONE"
+
+# Then OpenCode automatically:
+# 1. Works on the task
+# 2. Session becomes idle
+# 3. session.idle hook intercepts
+# 4. Hook feeds the SAME prompt back
+# 5. Repeat until completion
+```
+
+The loop happens **inside your current session** - you don't need external bash loops. The plugin creates a self-referential feedback loop by intercepting session idle events.
+
+This creates a **self-referential feedback loop** where:
+
+- The prompt never changes between iterations
+- Previous work persists in files
+- Each iteration sees modified files and git history
+- OpenCode autonomously improves by reading its own past work in files
+
+## Installation
+
+### Option 1: NPM Package (Recommended)
+
+```bash
+npm install opencode-ralph-wiggum
+```
+
+The postinstall script automatically copies the command files to `~/.config/opencode/command/`.
+
+Then add the plugin to your `opencode.json`:
+
+```json
+{
+  "plugin": ["opencode-ralph-wiggum"]
+}
+```
+
+### Option 2: Manual Installation
+
+Copy the files from this plugin to your opencode config:
+
+```bash
+# Copy plugin
+cp plugins/ralph-wiggum/src/index.ts ~/.config/opencode/plugin/ralph-wiggum.ts
+
+# Copy commands
+cp plugins/ralph-wiggum/commands/*.md ~/.config/opencode/command/
+```
+
+Then configure in your `opencode.json`:
+
+```json
+{
+  "plugin": ["~/.config/opencode/plugin/ralph-wiggum.ts"]
+}
+```
+
+## Quick Start
+
+```bash
+/ralph-loop "Build a REST API for todos. Requirements: CRUD operations, input validation, tests. Output <promise>COMPLETE</promise> when done." --completion-promise "COMPLETE" --max-iterations 50
+```
+
+OpenCode will:
+
+- Implement the API iteratively
+- Run tests and see failures
+- Fix bugs based on test output
+- Iterate until all requirements met
+- Output the completion promise when done
+
+## Commands
+
+### /ralph-loop
+
+Start a Ralph loop in your current session.
+
+**Usage:**
+
+```bash
+/ralph-loop "<prompt>" --max-iterations <n> --completion-promise "<text>"
+```
+
+**Options:**
+
+- `--max-iterations <n>` - Stop after N iterations (default: unlimited)
+- `--completion-promise <text>` - Phrase that signals completion
+
+### /cancel-ralph
+
+Cancel the active Ralph loop.
+
+**Usage:**
+
+```bash
+/cancel-ralph
+```
+
+### /help
+
+Get detailed help on the Ralph Wiggum technique and commands.
+
+**Usage:**
+
+```bash
+/help
+```
+
+## Prompt Writing Best Practices
+
+### 1. Clear Completion Criteria
+
+Bad: "Build a todo API and make it good."
+
+Good:
+
+```markdown
+Build a REST API for todos.
+
+When complete:
+
+- All CRUD endpoints working
+- Input validation in place
+- Tests passing (coverage > 80%)
+- README with API docs
+- Output: <promise>COMPLETE</promise>
+```
+
+### 2. Incremental Goals
+
+Bad: "Create a complete e-commerce platform."
+
+Good:
+
+```markdown
+Phase 1: User authentication (JWT, tests)
+Phase 2: Product catalog (list/search, tests)
+Phase 3: Shopping cart (add/remove, tests)
+
+Output <promise>COMPLETE</promise> when all phases done.
+```
+
+### 3. Self-Correction
+
+Bad: "Write code for feature X."
+
+Good:
+
+```markdown
+Implement feature X following TDD:
+
+1. Write failing tests
+2. Implement feature
+3. Run tests
+4. If any fail, debug and fix
+5. Refactor if needed
+6. Repeat until all green
+7. Output: <promise>COMPLETE</promise>
+```
+
+### 4. Escape Hatches
+
+Always use `--max-iterations` as a safety net to prevent infinite loops on impossible tasks:
+
+```bash
+# Recommended: Always set a reasonable iteration limit
+/ralph-loop "Try to implement feature X" --max-iterations 20
+
+# In your prompt, include what to do if stuck:
+# "After 15 iterations, if not complete:
+#  - Document what's blocking progress
+#  - List what was attempted
+#  - Suggest alternative approaches"
+```
+
+**Note**: The `--completion-promise` uses exact string matching, so you cannot use it for multiple completion conditions (like "SUCCESS" vs "BLOCKED"). Always rely on `--max-iterations` as your primary safety mechanism.
+
+## Philosophy
+
+Ralph embodies several key principles:
+
+### 1. Iteration > Perfection
+
+Don't aim for perfect on first try. Let the loop refine the work.
+
+### 2. Failures Are Data
+
+"Deterministically bad" means failures are predictable and informative. Use them to tune prompts.
+
+### 3. Operator Skill Matters
+
+Success depends on writing good prompts, not just having a good model.
+
+### 4. Persistence Wins
+
+Keep trying until success. The loop handles retry logic automatically.
+
+## When to Use Ralph
+
+**Good for:**
+
+- Well-defined tasks with clear success criteria
+- Tasks requiring iteration and refinement (e.g., getting tests to pass)
+- Greenfield projects where you can walk away
+- Tasks with automatic verification (tests, linters)
+
+**Not good for:**
+
+- Tasks requiring human judgment or design decisions
+- One-shot operations
+- Tasks with unclear success criteria
+- Production debugging (use targeted debugging instead)
+
+## Real-World Results
+
+- Successfully generated 6 repositories overnight in Y Combinator hackathon testing
+- One $50k contract completed for $297 in API costs
+- Created entire programming language ("cursed") over 3 months using this approach
+
+## Learn More
+
+- Original technique: https://ghuntley.com/ralph/
+- Ralph Orchestrator: https://github.com/mikeyobrien/ralph-orchestrator
+
+## For Help
+
+Run `/help` in OpenCode for detailed command reference and examples.

package/commands/cancel-ralph.md

@@ -0,0 +1,16 @@
+---
+description: "Cancel active Ralph Wiggum loop"
+---
+
+# Cancel Ralph
+
+To cancel the Ralph loop:
+
+1. Check if `.opencode/ralph-loop.local.md` exists using Bash: `test -f .opencode/ralph-loop.local.md && echo "EXISTS" || echo "NOT_FOUND"`
+
+2. **If NOT_FOUND**: Say "No active Ralph loop found."
+
+3. **If EXISTS**:
+   - Read `.opencode/ralph-loop.local.md` to get the current iteration number from the `iteration:` field
+   - Remove the file using Bash: `rm .opencode/ralph-loop.local.md`
+   - Report: "Cancelled Ralph loop (was at iteration N)" where N is the iteration value

package/commands/ralph-loop.md

@@ -0,0 +1,81 @@
+---
+description: "Start Ralph Wiggum loop in current session"
+---
+
+# Ralph Loop Command
+
+!`export RALPH_ARGS='$ARGUMENTS' && node -e "
+var args = process.env.RALPH_ARGS || '';
+var fs = require('fs');
+var path = require('path');
+
+// Unescape the CLI escaping - remove outer quotes and unescape inner quotes
+args = args.trim();
+if ((args.startsWith('\"') && args.endsWith('\"')) || (args.startsWith(\"'\") && args.endsWith(\"'\"))) {
+args = args.slice(1, -1);
+}
+args = args.replace(/\\\\\"/g, '\"');
+
+var maxIterations = 0;
+var completionPromise = 'null';
+var prompt = args;
+
+var maxMatch = args.match(/--max-iterations\s+(\d+)/);
+if (maxMatch) {
+maxIterations = parseInt(maxMatch[1], 10);
+prompt = prompt.replace(/--max-iterations\s+\d+/, '');
+}
+
+var cpMatch = args.match(/--completion-promise\s+\"([^\"]+)\"/);
+if (cpMatch) {
+completionPromise = cpMatch[1];
+prompt = prompt.replace(/--completion-promise\s+\"[^\"]+\"/, '');
+} else {
+var cpMatch2 = args.match(/--completion-promise\s+(\S+)/);
+if (cpMatch2) {
+completionPromise = cpMatch2[1];
+prompt = prompt.replace(/--completion-promise\s+\S+/, '');
+}
+}
+
+prompt = prompt.trim().replace(/^\"|\"$/g, '');
+
+if (!prompt) {
+console.log('Error: No prompt provided.');
+console.log('Usage: /ralph-loop \"<prompt>\" [--max-iterations N] [--completion-promise TEXT]');
+process.exit(1);
+}
+
+var dir = '.opencode';
+fs.mkdirSync(dir, { recursive: true });
+
+var cpYaml = completionPromise === 'null' ? 'null' : '\"' + completionPromise + '\"';
+var lines = [
+'---',
+'active: true',
+'iteration: 1',
+'max_iterations: ' + maxIterations,
+'completion_promise: ' + cpYaml,
+'started_at: \"' + new Date().toISOString() + '\"',
+'---',
+'',
+prompt
+];
+
+fs.writeFileSync(path.join(dir, 'ralph-loop.local.md'), lines.join('\n') + '\n');
+
+console.log('Ralph loop activated!');
+console.log('Iteration: 1');
+console.log('Max iterations: ' + (maxIterations > 0 ? maxIterations : 'unlimited'));
+console.log('Completion promise: ' + (completionPromise !== 'null' ? completionPromise : 'none'));
+console.log('');
+console.log(prompt);
+"`
+
+Please work on the task described above. The Ralph loop is now active.
+
+When the session becomes idle, the session.idle hook will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.
+
+CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.
+
+To complete the loop, output: `<promise>YOUR_COMPLETION_PROMISE</promise>`

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import type { Plugin } from "@opencode-ai/plugin";
+/**
+ * Ralph Wiggum Plugin - Iterative AI Development
+ *
+ * This plugin implements the Ralph Wiggum technique: continuously feeding
+ * the same prompt to the AI until the task is complete.
+ *
+ * Usage:
+ * 1. Start a loop: /ralph-loop "Your task description" --max-iterations 10 --completion-promise "DONE"
+ * 2. Cancel a loop: /cancel-ralph
+ *
+ * The AI should output <promise>DONE</promise> when the task is complete.
+ */
+export declare const RalphWiggumPlugin: Plugin;
+export default RalphWiggumPlugin;

package/dist/index.js

@@ -0,0 +1,155 @@
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+const STATE_FILE = ".opencode/ralph-loop.local.md";
+function parseState(content) {
+    const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+    if (!frontmatterMatch)
+        return null;
+    const [, frontmatter, prompt] = frontmatterMatch;
+    const lines = frontmatter.split("\n");
+    const state = { prompt: prompt.trim() };
+    for (const line of lines) {
+        const [key, ...valueParts] = line.split(":");
+        if (!key)
+            continue;
+        const value = valueParts.join(":").trim();
+        switch (key.trim()) {
+            case "active":
+                state.active = value === "true";
+                break;
+            case "iteration":
+                state.iteration = parseInt(value, 10);
+                break;
+            case "max_iterations":
+                state.max_iterations = parseInt(value, 10);
+                break;
+            case "completion_promise":
+                state.completion_promise = value === "null" ? null : value.replace(/^"|"$/g, "");
+                break;
+            case "started_at":
+                state.started_at = value.replace(/^"|"$/g, "");
+                break;
+        }
+    }
+    if (state.active === undefined ||
+        state.iteration === undefined ||
+        state.max_iterations === undefined ||
+        !state.prompt) {
+        return null;
+    }
+    return state;
+}
+function extractPromiseText(text) {
+    const match = text.match(/<promise>(.*?)<\/promise>/s);
+    return match ? match[1].trim().replace(/\s+/g, " ") : null;
+}
+function updateIteration(filePath, newIteration) {
+    const content = readFileSync(filePath, "utf-8");
+    const updated = content.replace(/^iteration: \d+$/m, `iteration: ${newIteration}`);
+    writeFileSync(filePath, updated);
+}
+/**
+ * Ralph Wiggum Plugin - Iterative AI Development
+ *
+ * This plugin implements the Ralph Wiggum technique: continuously feeding
+ * the same prompt to the AI until the task is complete.
+ *
+ * Usage:
+ * 1. Start a loop: /ralph-loop "Your task description" --max-iterations 10 --completion-promise "DONE"
+ * 2. Cancel a loop: /cancel-ralph
+ *
+ * The AI should output <promise>DONE</promise> when the task is complete.
+ */
+export const RalphWiggumPlugin = async ({ client, directory }) => {
+    const stateFilePath = join(directory, STATE_FILE);
+    // Track if completion was detected to prevent race conditions
+    let completionDetected = false;
+    return {
+        event: async ({ event }) => {
+            // Check message.part.updated events for completion promise
+            // This happens BEFORE session goes idle, so we can detect early
+            if (event.type === "message.part.updated") {
+                const props = event.properties;
+                const part = props?.part;
+                // Only check text parts with completed status (time.end is set)
+                if (part?.type === "text" && part?.text && part?.time?.end && existsSync(stateFilePath)) {
+                    const content = readFileSync(stateFilePath, "utf-8");
+                    const state = parseState(content);
+                    if (state?.completion_promise && !completionDetected) {
+                        // Skip if this text is part of the user's prompt
+                        if (part.text.includes(state.prompt.slice(0, 30))) {
+                            return;
+                        }
+                        const promiseText = extractPromiseText(part.text);
+                        if (promiseText === state.completion_promise) {
+                            console.log(`Ralph loop: Detected <promise>${state.completion_promise}</promise> - task complete!`);
+                            completionDetected = true;
+                            unlinkSync(stateFilePath);
+                            return;
+                        }
+                    }
+                }
+                return;
+            }
+            // Handle session idle to continue the loop
+            const isIdle = event.type === "session.idle" ||
+                (event.type === "session.status" && event.properties?.status?.type === "idle");
+            if (!isIdle)
+                return;
+            // If completion was already detected, don't continue
+            if (completionDetected) {
+                return;
+            }
+            const sessionID = event.properties?.sessionID;
+            // Check if ralph-loop is active
+            if (!existsSync(stateFilePath))
+                return;
+            const content = readFileSync(stateFilePath, "utf-8");
+            const state = parseState(content);
+            if (!state || !state.active) {
+                return;
+            }
+            console.log("Ralph loop: session idle, iteration " + state.iteration);
+            // Validate numeric fields
+            if (isNaN(state.iteration) || isNaN(state.max_iterations)) {
+                console.error("Ralph loop: State file corrupted - invalid numeric fields");
+                unlinkSync(stateFilePath);
+                return;
+            }
+            // Check if max iterations reached
+            if (state.max_iterations > 0 && state.iteration >= state.max_iterations) {
+                console.log(`Ralph loop: Max iterations (${state.max_iterations}) reached.`);
+                unlinkSync(stateFilePath);
+                return;
+            }
+            // Not complete - continue loop with SAME PROMPT
+            const nextIteration = state.iteration + 1;
+            updateIteration(stateFilePath, nextIteration);
+            // Build system message
+            const systemMsg = state.completion_promise
+                ? `Ralph iteration ${nextIteration} | To stop: output <promise>${state.completion_promise}</promise> (ONLY when statement is TRUE - do not lie to exit!)`
+                : `Ralph iteration ${nextIteration} | No completion promise set - loop runs infinitely`;
+            console.log(systemMsg);
+            // Send the same prompt back to continue the session
+            try {
+                if (sessionID) {
+                    await client.session.promptAsync({
+                        path: { id: sessionID },
+                        body: {
+                            parts: [
+                                {
+                                    type: "text",
+                                    text: `[${systemMsg}]\n\n${state.prompt}`,
+                                },
+                            ],
+                        },
+                    });
+                }
+            }
+            catch (err) {
+                console.error("Ralph loop: Failed to send prompt", err);
+            }
+        },
+    };
+};
+export default RalphWiggumPlugin;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@sureshsankaran/ralph-wiggum",
+  "version": "0.1.0",
+  "description": "Ralph Wiggum iterative AI development plugin for OpenCode - continuously loops the same prompt until task completion",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "commands",
+    "scripts"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "postinstall": "node scripts/postinstall.js"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "ralph-wiggum",
+    "ai",
+    "iterative",
+    "automation"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anomalyco/opencode.git",
+    "directory": "plugins/ralph-wiggum"
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.0.224",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+
+import { copyFileSync, mkdirSync, existsSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { homedir } from "node:os"
+import { fileURLToPath } from "node:url"
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const packageRoot = join(__dirname, "..")
+
+const configDir = join(homedir(), ".config", "opencode", "command")
+
+// Create command directory if it doesn't exist
+if (!existsSync(configDir)) {
+  mkdirSync(configDir, { recursive: true })
+  console.log(`Created directory: ${configDir}`)
+}
+
+// Copy command files
+const commands = ["ralph-loop.md", "cancel-ralph.md"]
+const commandsDir = join(packageRoot, "commands")
+
+for (const cmd of commands) {
+  const src = join(commandsDir, cmd)
+  const dest = join(configDir, cmd)
+
+  if (existsSync(src)) {
+    copyFileSync(src, dest)
+    console.log(`Installed command: ${cmd}`)
+  } else {
+    console.warn(`Warning: Command file not found: ${src}`)
+  }
+}
+
+console.log("")
+console.log("Ralph Wiggum commands installed!")
+console.log("")
+console.log("Next step: Add the plugin to your opencode config:")
+console.log("")
+console.log("  In opencode.json:")
+console.log("  {")
+console.log('    "plugin": ["opencode-ralph-wiggum"]')
+console.log("  }")
+console.log("")
+console.log("Usage:")
+console.log('  /ralph-loop "Your task" --max-iterations 10 --completion-promise "DONE"')
+console.log("  /cancel-ralph")
+console.log("")