@pageai/ralph-loop 1.12.0 → 1.14.0

package/README.md

@@ -1,10 +1,14 @@
 # A Ralph Wiggum Loop implementation that works™
 
-Ralph is a long-running AI agent loop. Ralph automates software development tasks by iteratively working through a task list until completion.
+[![@pageai/ralph-loop version](https://img.shields.io/npm/v/@pageai/ralph-loop?label=npm&style=flat)](https://github.com/pageai-pro/ralph-loop)
 
-This is an implementation that actually works, containing 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.
+Ralph is a long-running AI agent loop. Ralph automates software development tasks by iteratively working through a task list until completion. This allows for long running agent loops, effectively enabling AI to code for days at a time.
 
-![Ralph Wiggum Loop](https://github.com/user-attachments/assets/052d5290-7e83-4bfb-a6b5-6be761cbe890)
+This is an implementation that actually works, containing 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, but supports [many other agentic AI CLIs](#running-with-a-different-agentic-cli).
+
+#### 👉 [Watch the video](https://www.youtube.com/watch?v=3TL8Ez66I3o) for an in-depth walkthrough.
+
+[![Ralph Wiggum Loop](https://github.com/user-attachments/assets/be94b8ba-b073-489d-b07e-d11db975a907)](https://www.youtube.com/watch?v=3TL8Ez66I3o)
 
 - [Getting Started](#getting-started)
   - [(Optional) Set up code base](#optional-set-up-code-base)
@@ -17,7 +21,6 @@ This is an implementation that actually works, containing a hackable script so y
 - [How It Works](#how-it-works)
 - [How Is This Different from Other Ralphs?](#how-is-this-different-from-other-ralphs)
 - [Steering the Agent](#steering-the-agent)
-- [Features](#features)
 - [Support](#support)
   - [Promise Tags](#promise-tags)
   - [Exit Codes](#exit-codes)
@@ -41,7 +44,7 @@ This is an implementation that actually works, containing a hackable script so y
 I recommend using a CLI to bootstrap your project with the necessary tools and dependencies, e.g.:
 
 ```bash
-npx @tanstack/cli create lib --add-ons shadcn,eslint,form,tanstack-query,nitro --no-git
+npx @tanstack/cli create lib --add-ons eslint,form,tanstack-query,nitro --no-git
 ```
 
 > If you must start from a blank slate, which is not recommended, see [Starting from scratch](#starting-from-scratch). You can also go for a more barebone start by running `npx create-vite@latest src --template react-ts`
@@ -84,15 +87,20 @@ Requirements:
 // etc.
 ```
 
-Pro tips:
+<details>
+<summary><strong>✨ Pro tips</strong></summary>
+
 - mention libraries and frameworks you want to use
-- mention env variables, e.g. for database, 3rd party API keys, etc. Store them in a .env file that you add to **.gitignore**
+- mention env variables, e.g. for DB, 3rd party API keys, etc. Store them in `.env` and add it to **.gitignore**
 - describe user flows and journeys
 - add relevant docs and UI references if applicable inside `/docs` and mention them in the requirements
 - be as descriptive as possible
 - *it's fine to write in your own language*
 
-Then follow the Skill's instructions and verify the PRD and then tasks.<br/>
+</details>
+<br/>
+
+Then, follow the Skill's instructions and verify the PRD and then tasks.<br/>
 **It is highly recommended that you review individual task requirements before starting the loop. Review EACH TASK INDIVIDUALLY.**
 
 ### 3️⃣ Step 3: Set up the agent inside Docker sandbox
@@ -162,7 +170,7 @@ 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
+4. Complete task, take screenshot, update task status and commit changes
 5. Repeat until all tasks pass or max iterations reached
 
 ## How Is This Different from Other Ralphs?
@@ -172,10 +180,27 @@ The script follows the original concepts of the Ralph Wiggum Loop, working with
 
 It also works generically with any task set.
 
+<details>
+<summary><strong>✨ Features</strong></summary>
+
+- **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
+- **Steering** - Allows prioritizing critical work that needs to be done before the loop can continue
+</details>
+
+<br/>
 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 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
@@ -189,19 +214,6 @@ While the loop is running, you can edit the `.agent/STEERING.md` file to add cri
 
 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.
@@ -258,6 +270,8 @@ Skills are reusable agent capabilities that provide specialized knowledge and wo
 | `prd-creator`                 | Create PRDs and task breakdowns for Ralph               |
 | `skill-creator`               | Create new skills                                       |
 | `vercel-react-best-practices` | React/Next.js performance patterns                      |
+| `mysql`                       | MySQL/InnoDB schema, indexing, query tuning, and ops    |
+| `postgres`                    | PostgreSQL best practices and query optimization        |
 | `web-design-guidelines`       | UI/UX design principles                                 |
 
 ### Skills Directory Structure
@@ -269,18 +283,14 @@ Skills are symlinked from `.agent/skills/` to multiple locations for cross-tool
 .agent/skills/
     ├── component-refactoring/
     ├── e2e-tester/
-    ├── frontend-code-review/
-    ├── frontend-testing/
-    ├── prd-creator/
-    ├── skill-creator/
-    ├── vercel-react-best-practices/
-    └── web-design-guidelines/
+    ├── postgres/
+    ├── ...
 
 # Symlinks -> .agent/skills/*
-.agents/skills/
-.claude/skills/
-.codex/skills/
-.cursor/skills/
+.agents/skills/*
+.claude/skills/*
+.codex/skills/*
+.cursor/skills/*
 ```
 
 ## Reference
@@ -324,29 +334,28 @@ export default defineConfig({
 If you are using Vitest, here is a recommended configuration:
 
 ```typescript:vitest.config.ts
-import { defineConfig } from 'vitest/config'
-import react from '@vitejs/plugin-react'
-import path from 'path'
+import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+import path from "path";
 
 export default defineConfig({
   plugins: [react()],
   test: {
-    environment: 'jsdom',
+    environment: "node",
     globals: true,
-    setupFiles: ['./vitest.setup.ts'],
-    include: ['**/*.test.{ts,tsx}'],
-    exclude: ['node_modules', '.next', 'tests'],
+    include: ["lib/**/*.test.ts", "lib/**/*.test.tsx"],
+    // setupFiles: ['./vitest.setup.ts'], // Include this if using Next.js
   },
   resolve: {
     alias: {
-      '@': path.resolve(__dirname, './'),
+      "@": path.resolve(__dirname),
     },
   },
-})
+});
 
 ```
 
-And:
+If you are using Next.js, you'll also need a `vitest.setup.ts` file to mock the `next/image` and `next/link` components.
 
 ```typescript:vitest.setup.ts
 import '@testing-library/jest-dom/vitest'
@@ -388,8 +397,8 @@ docker sandbox run codex . # for Codex CLI
 docker sandbox run gemini . # for Gemini CLI
 ```
 
-Docker currently supports: `claude`, `codex`, `gemini`, `cagent`, `kiro`.
-See more in [Docker's docs](https://docs.docker.com/ai/sandboxes/migration/).
+Docker currently supports: `claude`, `codex`, `opencode`,`copilot`, `gemini`, `cagent`, `kiro` and more.
+See all supported agentic AI CLIs in [Docker's docs](https://docs.docker.com/ai/sandboxes/agents/).
 
 ### Starting from scratch
 

package/bin/cli.js

@@ -8,15 +8,16 @@
 
 const fs = require('fs');
 const path = require('path');
-const { execSync } = require('child_process');
 const display = require('./lib/display');
 const { copyFile, copyDir, mergeDir, exists, ensureDir } = require('./lib/copy');
 const { isGitRepo, initGitRepo } = require('./lib/git');
 const { isShadcnProject, installAllComponents } = require('./lib/shadcn');
+const { setupPlaywright } = require('./lib/playwright');
+const { setupVitest } = require('./lib/vitest');
+const { DEFAULT_APP_DIR } = require('./lib/consts');
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const TARGET_DIR = process.cwd();
-const DEFAULT_APP_DIR = 'lib';
 
 // Directories to ensure exist (created even if source doesn't exist)
 const DIRS_TO_ENSURE = [
@@ -161,7 +162,18 @@ async function main() {
     process.exit(0);
   }
 
-  // Prompt 3 — Dev server address
+  // Prompt 3 — Install Vitest
+  const installVitest = await clack.confirm({
+    message: 'Set up Vitest for unit testing?',
+    initialValue: true,
+  });
+
+  if (clack.isCancel(installVitest)) {
+    clack.cancel('Setup cancelled.');
+    process.exit(0);
+  }
+
+  // Prompt 4 — Dev server address
   const devServerRaw = await clack.text({
     message: 'Where does your dev server run?',
     placeholder: 'localhost:3000',
@@ -341,32 +353,12 @@ async function main() {
 
   // Playwright setup
   if (installPlaywright) {
-    console.log();
-    display.printStep('🎭', 'Playwright setup');
-
-    // Copy playwright config to app directory
-    const playwrightSrc = path.join(TARGET_DIR, 'scripts/assets/playwright.config.ts');
-    const playwrightDest = path.join(TARGET_DIR, appDir, 'playwright.config.ts');
-
-    if (exists(playwrightSrc)) {
-      copyFile(playwrightSrc, playwrightDest);
-      display.printSuccess(`playwright.config.ts → ${appDir}/`);
-    }
+    setupPlaywright(clack, TARGET_DIR, appDir);
+  }
 
-    // Install Playwright browsers
-    const s = clack.spinner();
-    s.start('Installing Playwright browsers (chromium)...');
-    try {
-      execSync('npx playwright install --with-deps chromium', {
-        cwd: path.join(TARGET_DIR, appDir),
-        stdio: 'pipe',
-      });
-      s.stop('Playwright browsers installed');
-    } catch (err) {
-      s.stop('Playwright browser install failed');
-      display.printWarning('Could not install Playwright browsers. Run manually:');
-      display.printWarning(`  cd ${appDir} && npx playwright install --with-deps chromium`);
-    }
+  // Vitest setup
+  if (installVitest) {
+    setupVitest(clack, TARGET_DIR, appDir);
   }
 
   // Final setup steps (git init, shadcn install)

package/bin/lib/consts.js

@@ -0,0 +1,9 @@
+/**
+ * Shared constants for Ralph Loop CLI
+ */
+
+const DEFAULT_APP_DIR = 'lib';
+
+module.exports = {
+  DEFAULT_APP_DIR,
+};

package/bin/lib/playwright.js

@@ -0,0 +1,48 @@
+/**
+ * Playwright module for Ralph Loop CLI
+ * Copies config and installs Playwright browsers
+ */
+
+const path = require('path');
+const { execSync } = require('child_process');
+const { copyFile, exists } = require('./copy');
+const display = require('./display');
+
+/**
+ * Copies playwright.config.ts into the app directory and installs Chromium.
+ * @param {object} clack - @clack/prompts module (passed in because it's ESM)
+ * @param {string} targetDir - Project root (TARGET_DIR)
+ * @param {string} appDir - Relative app source directory
+ */
+function setupPlaywright(clack, targetDir, appDir) {
+  console.log();
+  display.printStep('🎭', 'Playwright setup');
+
+  // Copy playwright config to app directory
+  const playwrightSrc = path.join(targetDir, 'scripts/assets/playwright.config.ts');
+  const playwrightDest = path.join(targetDir, appDir, 'playwright.config.ts');
+
+  if (exists(playwrightSrc)) {
+    copyFile(playwrightSrc, playwrightDest);
+    display.printSuccess(`playwright.config.ts → ${appDir}/`);
+  }
+
+  // Install Playwright browsers
+  const s = clack.spinner();
+  s.start('Installing Playwright browsers (chromium)...');
+  try {
+    execSync('npx playwright install --with-deps chromium', {
+      cwd: path.join(targetDir, appDir),
+      stdio: 'pipe',
+    });
+    s.stop('Playwright browsers installed');
+  } catch (err) {
+    s.stop('Playwright browser install failed');
+    display.printWarning('Could not install Playwright browsers. Run manually:');
+    display.printWarning(`  cd ${appDir} && npx playwright install --with-deps chromium`);
+  }
+}
+
+module.exports = {
+  setupPlaywright,
+};

package/bin/lib/shadcn.js

@@ -1,6 +1,6 @@
 /**
  * shadcn/ui module for Ralph Loop CLI
- * Detects shadcn config and installs all components
+ * Detects React projects, initializes shadcn if needed, and installs all components
  */
 
 const fs = require('fs');
@@ -15,7 +15,7 @@ const SHADCN_SCHEMA = 'https://ui.shadcn.com/schema.json';
  * @param {string} dir - Directory path to check
  * @returns {boolean}
  */
-function isShadcnProject(dir) {
+function hasShadcnConfig(dir) {
   const configPath = path.join(dir, 'components.json');
   if (!exists(configPath)) return false;
 
@@ -28,10 +28,55 @@ function isShadcnProject(dir) {
 }
 
 /**
- * Installs all shadcn/ui components in the given directory
+ * Checks if a directory is a React project by looking for react in package.json
+ * @param {string} dir - Directory path to check
+ * @returns {boolean}
+ */
+function isReactProject(dir) {
+  const pkgPath = path.join(dir, 'package.json');
+  if (!exists(pkgPath)) return false;
+
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
+    return 'react' in allDeps;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Returns true if shadcn components should be installed.
+ * Either the project already has a shadcn config, or it's a React project
+ * where we can init shadcn first.
+ * @param {string} dir - Directory path to check
+ * @returns {boolean}
+ */
+function isShadcnProject(dir) {
+  return hasShadcnConfig(dir) || isReactProject(dir);
+}
+
+/**
+ * Initializes shadcn in the given directory with default settings.
+ * @param {string} dir - Directory path to run the init in
+ */
+function initShadcn(dir) {
+  execSync('npx shadcn@latest init -y -d 2>&1', {
+    cwd: dir,
+    stdio: 'pipe',
+  });
+}
+
+/**
+ * Installs all shadcn/ui components in the given directory.
+ * Runs init first if no components.json exists.
  * @param {string} dir - Directory path to run the install in
  */
 function installAllComponents(dir) {
+  if (!hasShadcnConfig(dir)) {
+    initShadcn(dir);
+  }
+
   execSync('npx shadcn@latest add --all --yes --overwrite 2>&1', {
     cwd: dir,
     stdio: 'pipe',

package/bin/lib/vitest.js

@@ -0,0 +1,59 @@
+/**
+ * Vitest module for Ralph Loop CLI
+ * Copies config and installs Vitest dependencies
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+const { copyFile, exists } = require('./copy');
+const display = require('./display');
+const { DEFAULT_APP_DIR } = require('./consts');
+
+/**
+ * Copies vitest.config.ts into the app directory, patches the include
+ * paths to match appDir, and installs vitest + react plugin.
+ * @param {object} clack - @clack/prompts module (passed in because it's ESM)
+ * @param {string} targetDir - Project root (TARGET_DIR)
+ * @param {string} appDir - Relative app source directory
+ */
+function setupVitest(clack, targetDir, appDir) {
+  console.log();
+  display.printStep('⚡', 'Vitest setup');
+
+  // Copy vitest config to app directory
+  const vitestSrc = path.join(targetDir, 'scripts/assets/vitest.config.ts');
+  const vitestDest = path.join(targetDir, appDir, 'vitest.config.ts');
+
+  if (exists(vitestSrc)) {
+    copyFile(vitestSrc, vitestDest);
+
+    // Patch include paths to match the user's app directory
+    if (appDir !== DEFAULT_APP_DIR) {
+      const content = fs.readFileSync(vitestDest, 'utf8');
+      const updated = content.replaceAll('lib/**/', `${appDir}/**/`);
+      fs.writeFileSync(vitestDest, updated, 'utf8');
+    }
+
+    display.printSuccess(`vitest.config.ts → ${appDir}/`);
+  }
+
+  // Install Vitest dependencies
+  const s = clack.spinner();
+  s.start('Installing Vitest dependencies...');
+  try {
+    execSync('npm install --save-dev vitest @vitejs/plugin-react', {
+      cwd: path.join(targetDir, appDir),
+      stdio: 'pipe',
+    });
+    s.stop('Vitest dependencies installed');
+  } catch (err) {
+    s.stop('Vitest install failed');
+    display.printWarning('Could not install Vitest dependencies. Run manually:');
+    display.printWarning(`  cd ${appDir} && npm install --save-dev vitest @vitejs/plugin-react`);
+  }
+}
+
+module.exports = {
+  setupVitest,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pageai/ralph-loop",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "publishConfig": {
     "access": "public"
   },

package/scripts/assets/vitest.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from "vitest/config";
+import react from "@vitejs/plugin-react";
+import path from "path";
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: "node",
+    globals: true,
+    include: ["lib/**/*.test.ts", "lib/**/*.test.tsx"],
+  },
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname),
+    },
+  },
+});