@pageai/ralph-loop 1.0.0

package/README.md

@@ -0,0 +1,236 @@
+# Ralph Loop
+
+A long-running AI agent loop. Ralph automates software development tasks by iteratively working through a task list until completion.
+
+This is a hackable script so you can configure it to your env and favorite agentic AI CLI. It's set up by default to use Claude Code in a Docker sandbox.
+
+## Quick Start
+
+```bash
+# Run the agent loop (default: 10 iterations)
+./ralph.sh
+
+# Run with custom iteration limit
+./ralph.sh 5
+./ralph.sh -n 5
+./ralph.sh --max-iterations 5
+
+# Run exactly one iteration
+./ralph.sh --once
+
+# Show help
+./ralph.sh --help
+```
+
+> NB: you might need to run `chmod +x ralph.sh` to make the script executable.
+
+## How It Works
+
+Each iteration, Ralph will:
+1. Find the highest-priority incomplete task from `.agent/tasks.json`
+2. Work through the task steps defined in `.agent/tasks/TASK-{ID}.json`
+3. Run tests, linting, and type checking
+4. Update task status and commit changes
+5. Repeat until all tasks pass or max iterations reached
+
+## How Is This Different from Other Ralphs?
+
+This was kept hackable so you can make it your own.<br/>
+The script follows the original concepts of the Ralph Wiggum Loop, working with fresh contexts and providing clear verifiable feedback.
+
+It also works generically with any task set.
+
+Besides that:
+
+- it allows you to dump unstructured requirements and have the agent create a PRD and task list for you.
+- it uses a task lookup table with individual detailed steps -> more scalable as you get 100s of tasks done.
+- it's sandboxed and more secure
+- it shows progress and stats so you can keep an eye on what's been done
+- it instructs the agent to write and run automated tests and screenshots per task
+- it provides observability and traceability of the agent's work, showing a stream of output and capturing full historical logs per iteration
+
+## Getting Started
+
+### Step 1: Create a PRD
+
+Use the `prd-creator` skill to generate a PRD from your requirements:
+
+```
+Use the prd-creator skill to help me create a PRD and task list for these requirements:
+
+- A SaaS product that helps users manage their finances.
+- Target audience: Small business owners and freelancers.
+- Core features:
+  - Track income and expenses.
+  - Create and send invoices.
+  - Track payments and receipts.
+  - Generate reports and insights.
+  - Connect to bank accounts and credit cards.
+  - Connect to accounting software.
+  - Connect to payment processors.
+- Next.js web app with Tailwind CSS and TypeScript.
+- Use the shadcn/ui library for components.
+
+// etc.
+```
+
+Follow the skill's instructions and verify the PRD and then tasks.
+**It is highly recommended that you review individual task requirements before starting the loop. Review EACH TASK INDIVIDUALLY.**
+
+### Step 3: Set up the agent inside Docker sandbox
+
+Authenticate inside the Docker sandbox before running Ralph. Run:
+
+```bash
+docker sandbox run --credentials host claude
+```
+
+And follow the instructions to log in into Claude Code.
+
+> Answer "Yes" to "Bypass Permissions mode", that's the exact reason why you are using the Docker sandbox.
+
+### Step 4: Run Ralph
+
+```bash
+./ralph.sh -n 50 # Run Ralph Loop with 50 iterations
+```
+
+### Adjusting to your language/framework
+
+This script assumes the following are installed:
+- [Playwright](https://playwright.dev/) for e2e testing
+- [Vitest](https://vitest.dev/) for unit testing
+- [TypeScript](https://www.typescriptlang.org/) for type checking
+- [ESLint](https://eslint.org/) for linting
+- [Prettier](https://prettier.io/) for formatting
+
+I recommend using a CLI to bootstrap your project with the necessary tools and dependencies, e.g.:
+
+```bash
+npx create-vite@latest my-app --template react-ts
+# or
+npx create-next-app@latest my-app
+```
+
+If you must start from a blank slate, which is not recommended, you can use the following commands to install the necessary tools and dependencies:
+
+Install with:
+
+```bash
+npm i @playwright/test vitest jsdom typescript eslint prettier -D
+
+# If using React, also recommend installing:
+npm i @vitejs/plugin-react @testing-library/dom @testing-library/jest-dom @testing-library/react @testing-library/user-event -D
+```
+
+--------------------------------
+
+⚠️ If you are using a different language or testing framework, please adjust `.agent/PROMPT.md` to reflect your setup, server ports and startup commands etc.
+
+⚠️ The default "mode" is "implementation". Depending on your use case, you might want to change `.agent/PROMPT.md` to a different mode, e.g. "refactor", "review", "test" etc.
+
+## Steering the Agent
+
+In some cases, you might notice the agent is having trouble, slowed down or struggling to overcome a blocker.
+
+While the loop is running, you can edit the `.agent/STEERING.md` file to add critical work that needs to be done before the loop can continue.
+
+The agent will check this file each iteration and if it finds any critical work, it will skip tasks and complete the critical work first.
+
+## Features
+
+- **PRD generation** - Creates a PRD and task list from requirements
+- **Task lookup table generation** - Creates a task lookup table from the PRD
+- **Task breakdown + step generation** - Breaks down each task into manageable steps
+- **Iteration tracking** - Shows progress through iterations with timing
+- **Stream preview** - Shows live output from the Agent
+- **Step detection** - Identifies current activity (Thinking, Implementing, Testing, etc.)
+- **Screenshot capture** - Captures a screenshot of the current screen
+- **Notifications** - Alerts when human input is needed
+- **History logging** - Saves clean output from each iteration
+- **Timing** - Shows timing metrics for each iteration and total time
+
+## Support
+
+The `ralph.sh` script is designed to be hackable.
+It is configured to use Claude Code in a Docker sandbox by default, but with a one-liner change you can change it to use any other agentic AI CLI.
+
+Check the `ralph.sh` script around `# 👉 This is the main command loop.` for the main command loop.
+
+> NB: skills are supported by all major agentic AI CLIs via symlinks.
+
+### Promise Tags
+
+Ralph uses semantic tags to communicate status:
+- `<promise>COMPLETE</promise>` - All tasks finished successfully
+- `<promise>BLOCKED:reason</promise>` - Agent needs human help
+- `<promise>DECIDE:question</promise>` - Agent needs a decision
+
+### Exit Codes
+
+| Code | Meaning                        |
+| ---- | ------------------------------ |
+| 0    | COMPLETE - All tasks finished  |
+| 1    | MAX_ITERATIONS - Reached limit |
+| 2    | BLOCKED - Needs human help     |
+| 3    | DECIDE - Needs human decision  |
+
+## Structure
+
+```
+.agent/
+├── PROMPT.md           # Prompt sent to Agent each iteration
+├── tasks.json          # Task lookup table (required)
+├── tasks/              # Individual task specs (TASK-{ID}.json)
+├── prd/
+│   ├── PRD.md          # Product requirements document
+│   └── SUMMARY.md      # Short project overview sent to Agent each iteration
+├── logs/
+│   └── LOG.md          # Progress log (auto-created)
+├── history/            # Iteration output logs
+└── skills/             # Shared skills (source of truth)
+```
+
+## Skills
+
+Skills are reusable agent capabilities that provide specialized knowledge and workflows. The canonical source is `.agent/skills/`, which is symlinked to multiple agent tool directories for compatibility.
+
+### Available Skills
+
+| Skill                         | Description                                             |
+| ----------------------------- | ------------------------------------------------------- |
+| `component-refactoring`       | Patterns for splitting and refactoring React components |
+| `e2e-tester`                  | End-to-end testing workflows                            |
+| `frontend-code-review`        | Code quality and performance review guidelines          |
+| `frontend-testing`            | Unit and integration testing patterns                   |
+| `prd-creator`                 | Create PRDs and task breakdowns for Ralph               |
+| `skill-creator`               | Create new skills                                       |
+| `vercel-react-best-practices` | React/Next.js performance patterns                      |
+| `web-design-guidelines`       | UI/UX design principles                                 |
+
+### Skills Directory Structure
+
+Skills are symlinked from `.agent/skills/` to multiple locations for cross-tool compatibility:
+
+```
+ # Source of truth
+.agent/skills/
+    ├── component-refactoring/
+    ├── e2e-tester/
+    ├── frontend-code-review/
+    ├── frontend-testing/
+    ├── prd-creator/
+    ├── skill-creator/
+    ├── vercel-react-best-practices/
+    └── web-design-guidelines/
+
+# Symlinks -> .agent/skills/*
+.agents/skills/
+.claude/skills/
+.codex/skills/
+.cursor/skills/
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+
+/**
+ * CLI script for setting up a Ralph Loop in the current directory.
+ * Copies required files and folders, preserving symlinks.
+ * Merges directories that should preserve existing user files.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const display = require('./lib/display');
+const { copyFile, copyDir, mergeDir, exists } = require('./lib/copy');
+
+const PACKAGE_ROOT = path.resolve(__dirname, '..');
+const TARGET_DIR = process.cwd();
+
+// Files to copy (always overwrite)
+const FILES_TO_COPY = [
+  'ralph.sh',
+  'CLAUDE.md',
+  'AGENTS.md',
+  '.mcp.json',
+];
+
+// Single files within directories (always overwrite)
+const CONFIG_FILES = [
+  '.agent/PROMPT.md',
+  '.agent/STEERING.md',
+  '.agent/tasks.json',
+  '.agent/history/.gitignore',
+];
+
+// Directories to fully copy (overwrite)
+const DIRS_TO_COPY = [
+  'scripts',
+  '.agent/logs',
+  '.agent/prd',
+  '.agent/screenshots',
+  '.agent/tasks',
+];
+
+// Directories to merge (preserve existing files, add missing ones)
+const DIRS_TO_MERGE = [
+  '.agent/skills',
+  '.agents/skills',
+  '.claude/skills',
+  '.claude/agents',
+  '.claude/commands',
+  '.claude/hooks',
+  '.codex/skills',
+  '.cursor/skills',
+];
+
+// Other files in these directories to copy (with exclusions)
+const EXTRA_DIR_FILES = [
+  { dir: '.claude', exclude: ['settings.local.json', 'skills', 'agents', 'commands', 'hooks'] },
+];
+
+function main() {
+  display.showRalph();
+
+  // Check if we're in the package directory itself
+  if (path.resolve(TARGET_DIR) === path.resolve(PACKAGE_ROOT)) {
+    display.printError('Cannot run setup in the package directory itself.');
+    process.exit(1);
+  }
+
+  display.printLocation(TARGET_DIR);
+
+  // Copy individual files
+  display.printStep('📄', 'Core files');
+  for (const file of FILES_TO_COPY) {
+    const src = path.join(PACKAGE_ROOT, file);
+    const dest = path.join(TARGET_DIR, file);
+    if (exists(src)) {
+      copyFile(src, dest);
+      display.printSuccess(file);
+    } else {
+      display.printWarning(`${file} not found, skipping`);
+    }
+  }
+
+  // Copy config files
+  console.log();
+  display.printStep('⚙️ ', 'Config files');
+  for (const file of CONFIG_FILES) {
+    const src = path.join(PACKAGE_ROOT, file);
+    const dest = path.join(TARGET_DIR, file);
+    if (exists(src)) {
+      copyFile(src, dest);
+      display.printSuccess(file);
+    } else {
+      display.printWarning(`${file} not found, skipping`);
+    }
+  }
+
+  // Copy directories (full overwrite)
+  console.log();
+  display.printStep('📁', 'Directories');
+  for (const dir of DIRS_TO_COPY) {
+    const src = path.join(PACKAGE_ROOT, dir);
+    const dest = path.join(TARGET_DIR, dir);
+    if (exists(src)) {
+      copyDir(src, dest);
+      display.printSuccess(`${dir}/`);
+    } else {
+      display.printWarning(`${dir}/ not found, skipping`);
+    }
+  }
+
+  // Merge directories (preserve existing, add missing)
+  console.log();
+  display.printStep('🔗', 'Skills & tools (merge)');
+  for (const dir of DIRS_TO_MERGE) {
+    const src = path.join(PACKAGE_ROOT, dir);
+    const dest = path.join(TARGET_DIR, dir);
+    if (exists(src)) {
+      const result = mergeDir(src, dest);
+      if (result.skipped > 0 && result.copied === 0) {
+        display.printSkipped(`${dir}/`);
+      } else if (result.skipped > 0) {
+        display.printSuccess(`${dir}/ (+${result.copied} new, ${result.skipped} kept)`);
+      } else {
+        display.printSuccess(`${dir}/`);
+      }
+    } else {
+      display.printWarning(`${dir}/ not found, skipping`);
+    }
+  }
+
+  // Copy extra files from directories (with exclusions)
+  console.log();
+  display.printStep('📋', 'Extra config files');
+  for (const { dir, exclude } of EXTRA_DIR_FILES) {
+    const src = path.join(PACKAGE_ROOT, dir);
+    const dest = path.join(TARGET_DIR, dir);
+    if (exists(src)) {
+      const entries = fs.readdirSync(src, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.name === '.DS_Store') continue;
+        if (exclude.includes(entry.name)) continue;
+        if (entry.isDirectory()) continue; // Skip subdirs, handled separately
+
+        const srcFile = path.join(src, entry.name);
+        const destFile = path.join(dest, entry.name);
+        copyFile(srcFile, destFile);
+        display.printSuccess(`${dir}/${entry.name}`);
+      }
+    }
+  }
+
+  // Success message
+  display.showComplete();
+}
+
+main();

package/bin/lib/copy.js

@@ -0,0 +1,149 @@
+/**
+ * Copy module for Ralph Loop CLI
+ * Handles file/directory copying with merge support
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Ensures a directory exists, creating it recursively if needed
+ */
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+/**
+ * Copies a single file, preserving executable permissions
+ * @param {string} src - Source file path
+ * @param {string} dest - Destination file path
+ * @param {boolean} overwrite - If false, skip if destination exists
+ * @returns {{ copied: boolean, skipped: boolean }}
+ */
+function copyFile(src, dest, overwrite = true) {
+  if (!overwrite && fs.existsSync(dest)) {
+    return { copied: false, skipped: true };
+  }
+
+  ensureDir(path.dirname(dest));
+  fs.copyFileSync(src, dest);
+
+  // Preserve executable permission
+  const stats = fs.statSync(src);
+  if (stats.mode & 0o111) {
+    fs.chmodSync(dest, stats.mode);
+  }
+
+  return { copied: true, skipped: false };
+}
+
+/**
+ * Copies a symlink
+ * @param {string} src - Source symlink path
+ * @param {string} dest - Destination path
+ * @param {boolean} overwrite - If false, skip if destination exists
+ * @returns {{ copied: boolean, skipped: boolean }}
+ */
+function copySymlink(src, dest, overwrite = true) {
+  // Check if dest exists (as file or symlink)
+  let destExists = false;
+  try {
+    fs.lstatSync(dest);
+    destExists = true;
+  } catch {
+    destExists = false;
+  }
+
+  if (!overwrite && destExists) {
+    return { copied: false, skipped: true };
+  }
+
+  const linkTarget = fs.readlinkSync(src);
+
+  if (destExists) {
+    fs.unlinkSync(dest);
+  }
+
+  ensureDir(path.dirname(dest));
+  fs.symlinkSync(linkTarget, dest);
+
+  return { copied: true, skipped: false };
+}
+
+/**
+ * Copies a directory recursively
+ * @param {string} src - Source directory path
+ * @param {string} dest - Destination directory path
+ * @param {Object} options - Copy options
+ * @param {boolean} options.overwrite - If false, skip existing files (default: true)
+ * @param {string[]} options.exclude - Files/dirs to exclude
+ * @returns {{ copied: number, skipped: number }}
+ */
+function copyDir(src, dest, options = {}) {
+  const { overwrite = true, exclude = [] } = options;
+  let copied = 0;
+  let skipped = 0;
+
+  ensureDir(dest);
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+
+  for (const entry of entries) {
+    // Skip .DS_Store and excluded items
+    if (entry.name === '.DS_Store') continue;
+    if (exclude.includes(entry.name)) continue;
+
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      const result = copyDir(srcPath, destPath, options);
+      copied += result.copied;
+      skipped += result.skipped;
+    } else if (entry.isSymbolicLink()) {
+      const result = copySymlink(srcPath, destPath, overwrite);
+      if (result.copied) copied++;
+      if (result.skipped) skipped++;
+    } else {
+      const result = copyFile(srcPath, destPath, overwrite);
+      if (result.copied) copied++;
+      if (result.skipped) skipped++;
+    }
+  }
+
+  return { copied, skipped };
+}
+
+/**
+ * Merges a directory - copies only missing files/subdirs
+ * Existing files are preserved, new ones are added
+ * @param {string} src - Source directory path
+ * @param {string} dest - Destination directory path
+ * @param {string[]} exclude - Files/dirs to exclude
+ * @returns {{ copied: number, skipped: number }}
+ */
+function mergeDir(src, dest, exclude = []) {
+  return copyDir(src, dest, { overwrite: false, exclude });
+}
+
+/**
+ * Check if a path exists (file, directory, or symlink)
+ */
+function exists(filePath) {
+  try {
+    fs.lstatSync(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  ensureDir,
+  copyFile,
+  copySymlink,
+  copyDir,
+  mergeDir,
+  exists,
+};

package/bin/lib/display.js

@@ -0,0 +1,137 @@
+/**
+ * Display module for Ralph Loop CLI
+ * ASCII art, colors, and UI elements
+ */
+
+// ANSI color codes
+const colors = {
+  reset: '\x1b[0m',
+  yellow: '\x1b[33m',
+  green: '\x1b[32m',
+  cyan: '\x1b[36m',
+  red: '\x1b[31m',
+  dim: '\x1b[2m',
+  bold: '\x1b[1m',
+};
+
+const { reset: R, yellow: Y, green: G, cyan: C, red: RD, dim: D, bold: B } = colors;
+
+// Line width for catchphrases (matching display.sh)
+const LINE_WIDTH = 59;
+
+/**
+ * Creates a catchphrase line with centered text and ▒ padding
+ * Format: ■▒...text...▒■▒▒▓■ (59 chars total)
+ */
+function formatCatchphrase(text) {
+  const prefix = '■▒';
+  const suffix = '■▒▒▓■';
+  const contentWidth = LINE_WIDTH - prefix.length - suffix.length; // 52 chars for content
+
+  const padding = contentWidth - text.length;
+  const leftPad = Math.floor(padding / 2);
+  const rightPad = padding - leftPad;
+
+  return prefix + '▒'.repeat(leftPad) + text + '▒'.repeat(rightPad) + suffix;
+}
+
+// Catchphrases (text only, will be formatted)
+const catchphraseTexts = [
+  "I'm helping!",
+  "I'm doing my best!",
+  "I'm in danger!",
+  "I'm learnding!",
+  "My cat's breath smells like cat food.",
+  "Me fail English? That's unpossible!",
+  "I'm asking Claude to cook pasta!",
+  "I found a moon rock in my nose!",
+  "It tastes like burning!",
+  "When I grow up, I want to be a computer!",
+  "I'm a develotron!",
+  "I'm helpding AI!",
+  "I'm essential!",
+];
+
+function getRandomCatchphrase() {
+  const text = catchphraseTexts[Math.floor(Math.random() * catchphraseTexts.length)];
+  return formatCatchphrase(text);
+}
+
+function showRalph() {
+  const emptyLine = formatCatchphrase('');
+  const catchphrase = getRandomCatchphrase();
+
+  console.log(`
+${Y}██████╗  █████╗ ██╗     ██████╗ ██╗  ██╗
+██╔══██╗██╔══██╗██║     ██╔══██╗██║  ██║
+██████╔╝███████║██║     ██████╔╝███████║
+██╔══██╗██╔══██║██║     ██╔═══╝ ██╔══██║
+██║  ██║██║  ██║███████╗██║     ██║  ██║
+╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝  ╚═╝
+
+██╗      ██████╗  ██████╗ ██████╗
+██║     ██╔═══██╗██╔═══██╗██╔══██╗
+██║     ██║   ██║██║   ██║██████╔╝
+██║     ██║   ██║██║   ██║██╔═══╝
+███████╗╚██████╔╝╚██████╔╝██║
+╚══════╝ ╚═════╝  ╚═════╝ ╚═╝${R}
+
+${D}${emptyLine}${R}
+${Y}${catchphrase}${R}
+${D}${emptyLine}${R}
+${D}═══════════════════════════════════════════════════════════${R}
+ ${C}Ralph Wiggum Loop${R} ${D}・${R} Long-running AI agents
+`);
+}
+
+function showComplete() {
+  console.log(`
+${D}═══════════════════════════════════════════════════════════${R}
+${G}  ✓ Ralph Loop setup complete!${R}
+${D}═══════════════════════════════════════════════════════════${R}
+
+${Y}Next steps:${R}
+  ${C}1.${R} Review the copied files
+  ${C}2.${R} Create a PRD using the ${G}prd-creator${R} skill
+  ${C}3.${R} Run ${G}./ralph.sh${R} to start the loop
+
+${D}Learn more: ${C}https://github.com/pageai-pro/ralph-loop/${R}
+`);
+}
+
+function printStep(icon, text) {
+  console.log(`  ${icon} ${B}${text}${R}`);
+}
+
+function printSuccess(text) {
+  console.log(`     ${G}✓${R} ${D}${text}${R}`);
+}
+
+function printSkipped(text) {
+  console.log(`     ${D}○ ${text} (exists)${R}`);
+}
+
+function printWarning(text) {
+  console.log(`     ${Y}⚠${R} ${D}${text}${R}`);
+}
+
+function printError(text) {
+  console.log(`${RD}  ✗ Error: ${text}${R}\n`);
+}
+
+function printLocation(targetDir) {
+  console.log(`${B}Setting up Ralph Loop in:${R}`);
+  console.log(`  ${C}${targetDir}${R}\n`);
+}
+
+module.exports = {
+  colors,
+  showRalph,
+  showComplete,
+  printStep,
+  printSuccess,
+  printSkipped,
+  printWarning,
+  printError,
+  printLocation,
+};