npm package: @ralph-e-cli/ralph-e
Description: Autonomous AI development loop with integrated Playwright UI/UX validation, visual regression testing, and self-healing builds.
Latest version: 5.1.0

<p align="center">
  <img src="../assets/ralph-e.png" alt="Ralph-E" width="400">
</p>

# Ralph-E

Autonomous AI coding loop. Runs AI agents on tasks until done.

## Install

```bash
npm install -g @ralph-e-cli/ralph-e
```

## Quick Start

```bash
# Single task
ralph-e "add login button"

# Work through a task list
ralph-e --prd PRD.md
```

## Two Modes

**Single task** - just tell it what to do:
```bash
ralph-e "add dark mode"
ralph-e "fix the auth bug"
```

**Task list** - work through a PRD:
```bash
ralph-e              # uses PRD.md
ralph-e --prd tasks.md
```

## Project Config

Optional. Stores rules the AI must follow.

```bash
ralph-e --init              # auto-detects project settings
ralph-e --config            # view config
ralph-e --add-rule "use TypeScript strict mode"
```

Creates `.ralph-e/config.yaml`:
```yaml
project:
  name: "my-app"
  language: "TypeScript"
  framework: "Next.js"

commands:
  test: "npm test"
  lint: "npm run lint"
  build: "npm run build"

rules:
  - "use server actions not API routes"
  - "follow error pattern in src/utils/errors.ts"

boundaries:
  never_touch:
    - "src/legacy/**"
    - "*.lock"
```

## AI Engines

```bash
ralph-e              # Claude Code (default)
ralph-e --opencode   # OpenCode
ralph-e --cursor     # Cursor
ralph-e --codex      # Codex
ralph-e --qwen       # Qwen-Code
ralph-e --droid      # Factory Droid
ralph-e --copilot    # GitHub Copilot
```

### Model Override

```bash
ralph-e --model sonnet "add feature"    # use sonnet with Claude
ralph-e --sonnet "add feature"          # shortcut for above
ralph-e --opencode --model opencode/glm-4.7-free "task"
```

### Engine-Specific Arguments

Pass additional arguments to the underlying engine CLI using `--` separator:

```bash
ralph-e --copilot "add feature" -- --allow-all-tools --stream on
ralph-e --claude "fix bug" -- --no-permissions-prompt
```

## Task Sources

**Markdown file** (default):
```bash
ralph-e --prd PRD.md
```

**Markdown folder** (for large projects):
```bash
ralph-e --prd ./prd/
```
Reads all `.md` files in the folder and aggregates tasks.

**YAML**:
```bash
ralph-e --yaml tasks.yaml
```

**GitHub Issues**:
```bash
ralph-e --github owner/repo
ralph-e --github owner/repo --github-label "ready"
```

## Parallel Execution

```bash
ralph-e --parallel                  # 3 agents default
ralph-e --parallel --max-parallel 5 # 5 agents
```

Each agent gets isolated worktree + branch. Without `--create-pr`: auto-merges back with AI conflict resolution. With `--create-pr`: keeps branches, creates PRs. With `--no-merge`: keeps branches without merging.

### Smart Scheduling

Use AI to predict which files each task will modify, then automatically group non-conflicting tasks for safe parallel execution:

```bash
ralph-e --parallel --smart-schedule
ralph-e --parallel --smart-schedule --planning-model haiku  # use cheaper model for planning
```

Smart scheduling uses the DSatur graph coloring algorithm to:
1. Predict file modifications for each task using AI
2. Build a conflict graph where edges represent file overlaps
3. Color the graph to group non-conflicting tasks
4. Execute each color group in parallel

This allows more tasks to run simultaneously while avoiding merge conflicts.

### Sandbox Mode and Parallel Reliability

For large repos with big `node_modules` or dependency directories, use sandbox mode instead of git worktrees:

```bash
ralph-e --parallel --sandbox
```

Sandboxes are faster because they:
- **Symlink** read-only dependencies (`node_modules`, `.git`, `vendor`, `.venv`, etc.)
- **Copy** only source files that agents might modify

This avoids duplicating gigabytes of dependencies across worktrees. Changes are synced back to the original directory after each task completes.

**Parallel execution reliability:**
- If worktree operations fail (e.g., nested worktree repos), ralph-e falls back to sandbox mode automatically
- Retryable rate-limit or quota errors are detected and deferred for later retry
- Local changes are stashed before the merge phase and restored after
- Agents should not modify PRD files, `.ralph-e/progress.txt`, `.ralph-e-worktrees`, or `.ralph-e-sandboxes`

## Branch Workflow

```bash
ralph-e --branch-per-task                # branch per task
ralph-e --branch-per-task --create-pr    # + create PRs
ralph-e --branch-per-task --draft-pr     # + draft PRs
```

## Browser Automation

Ralph-E supports two approaches for browser-based testing:

### Option 1: Playwright MCP (Test While Coding)

Give the AI agent direct browser access so it can test as it builds. This enables a **code → test → fix** loop during development.

**Setup for Claude Code:**

Add to your `~/.claude/mcp.json` (or project `.claude/mcp.json`):

```json
{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropics/mcp-playwright"]
    }
  }
}
```

The AI agent gets tools like `browser_navigate`, `browser_click`, `browser_screenshot`, `browser_fill` and can test UI changes immediately after writing code.

**Setup for other agents:**

Use [agent-browser](https://agent-browser.dev) instead:

```bash
ralph-e "add login form" --browser    # enable browser automation
ralph-e "fix checkout" --no-browser   # disable browser automation
```

### Option 2: Ralph-E Validation (Test After Task)

Ralph-E's built-in Playwright validation runs after each task completes, providing a final quality gate before marking the task done. See [Playwright Visual Testing](#playwright-visual-testing) below.

### Recommended: Use Both

For maximum coverage, use both approaches together:

1. **Playwright MCP / agent-browser** - AI tests while coding (catches issues early)
2. **Ralph-E validation** - Final gate before commit (visual regression, accessibility, performance)

```yaml
# .ralph-e/config.yaml
playwright:
  enabled: true
  validateAfterTask: true
  onFailure: "block"  # Don't mark task complete if validation fails
```

This gives you: **AI-driven testing during development + automated validation before commit**.

## Playwright Visual Testing

Ralph-E includes integrated Playwright validation for UI/UX testing with visual regression, accessibility, and performance monitoring.

```bash
ralph-e "add feature" --playwright                    # enable Playwright validation
ralph-e "fix ui" --playwright --visual-regression     # with visual regression testing
ralph-e "update form" --playwright --accessibility    # with accessibility testing
ralph-e --playwright-url http://localhost:5173        # custom base URL
```

### Features

- **Visual Regression Testing**: Compare screenshots against baselines to catch unintended UI changes
- **Accessibility Testing**: WCAG compliance checking (wcag2a, wcag2aa, wcag2aaa)
- **Console Error Detection**: Catch JavaScript errors during page load
- **Network Failure Monitoring**: Detect failed API requests
- **Performance Budgets**: Monitor Core Web Vitals (LCP, CLS, TTFB)
- **Self-Healing Tests**: Learn from repeated failures and avoid making the same mistakes
- **Rollback on Failure**: Automatically revert changes when validation fails

### Configuration

Add to `.ralph-e/config.yaml`:

```yaml
playwright:
  enabled: true
  baseUrl: "http://localhost:3000"

  # Visual regression settings
  visualRegression: true
  baselineDir: ".ralph-e/baselines"
  diffDir: ".ralph-e/diffs"
  pixelThreshold: 0.1  # 0-1, how much difference is acceptable

  # Accessibility testing
  accessibilityCheck: true
  accessibilityStandard: "wcag2aa"  # wcag2a, wcag2aa, wcag2aaa

  # When to validate
  validateAfterTask: true
  validateBeforeCommit: true

  # What to do on failure
  onFailure: "warn"  # warn, block, or rollback

  # Routes to test
  routes:
    - "/"
    - "/dashboard"
    - "/settings"

  # Viewports to test
  viewports:
    - name: "desktop"
      width: 1280
      height: 720
    - name: "mobile"
      width: 375
      height: 667

  # Performance budgets (optional)
  performanceBudget:
    lcp: 2500   # Largest Contentful Paint (ms)
    cls: 0.1    # Cumulative Layout Shift
    ttfb: 800   # Time to First Byte (ms)

  # Dev server settings
  devServerCommand: "npm run dev"
  devServerReadyPattern: "ready|started|listening"
  devServerTimeout: 60000
```

### Self-Healing & Guardrails

When validation fails repeatedly (2+ times within 24 hours), Ralph-E automatically creates guardrails in `.ralph-e/guardrails.md`. These rules are injected into the AI agent's prompt to prevent repeating the same mistakes.

Example guardrail:
```markdown
## Accessibility Issue: /dashboard
- Route: `/dashboard`
- Issue: Button "Submit" missing aria-label
- **Rule**: Ensure all interactive elements have proper ARIA labels
- Suggestion: Add aria-label or aria-labelledby to interactive elements
```

### Rollback on Failure

When `onFailure: "rollback"` is set, Ralph-E creates a git checkpoint before validation. If validation fails, changes are automatically rolled back:

```yaml
playwright:
  enabled: true
  onFailure: "rollback"  # automatically revert on validation failure
```

The rollback creates a git tag checkpoint, stashes any uncommitted changes, and resets to the pre-task state.

## Options

| Flag | What it does |
|------|--------------|
| `--prd PATH` | task file or folder (auto-detected, default: PRD.md) |
| `--yaml FILE` | YAML task file |
| `--github REPO` | use GitHub issues |
| `--github-label TAG` | filter issues by label |
| `--model NAME` | override model for any engine |
| `--sonnet` | shortcut for `--claude --model sonnet` |
| `--parallel` | run parallel |
| `--max-parallel N` | max agents (default: 3) |
| `--sandbox` | use lightweight sandboxes instead of git worktrees |
| `--smart-schedule` | use AI to predict file conflicts and optimize parallel grouping |
| `--planning-model MODEL` | model for smart scheduling predictions (default: same as main) |
| `--no-merge` | skip auto-merge in parallel mode |
| `--branch-per-task` | branch per task |
| `--base-branch BRANCH` | base branch for PRs |
| `--create-pr` | create PRs |
| `--draft-pr` | draft PRs |
| `--no-tests` | skip tests |
| `--no-lint` | skip lint |
| `--fast` | skip tests + lint |
| `--no-commit` | don't auto-commit |
| `--browser` | enable browser automation |
| `--no-browser` | disable browser automation |
| `--playwright` | enable Playwright UI/UX validation |
| `--no-playwright` | disable Playwright validation |
| `--playwright-url URL` | base URL for Playwright (default: http://localhost:3000) |
| `--visual-regression` | enable visual regression testing (requires --playwright) |
| `--accessibility` | enable accessibility testing (requires --playwright) |
| `--max-iterations N` | stop after N tasks |
| `--max-retries N` | retries per task (default: 3) |
| `--retry-delay N` | delay between retries in seconds (default: 5) |
| `--dry-run` | preview only |
| `-v, --verbose` | debug output |
| `--init` | setup .ralph-e/ config |
| `--config` | show config |
| `--add-rule "rule"` | add rule to config |

## Webhook Notifications

Get notified when sessions complete via Discord, Slack, or custom webhooks.

Configure in `.ralph-e/config.yaml`:
```yaml
notifications:
  discord_webhook: "https://discord.com/api/webhooks/..."
  slack_webhook: "https://hooks.slack.com/services/..."
  custom_webhook: "https://your-api.com/webhook"
```

## Telemetry (Opt-in)

Collect session data for building AI agent evaluation datasets:

```yaml
# .ralph-e/config.yaml
telemetry:
  enabled: true
  privacyLevel: "anonymous"  # or "full" for prompts/responses
  format: "jsonl"            # or "deepeval" or "openai-evals"
  outputDir: ".ralph-e/telemetry"
```

Export formats:
- **jsonl**: Raw session data, one session per line
- **deepeval**: [DeepEval](https://docs.confident-ai.com/) compatible format for LLM evaluation
- **openai-evals**: [OpenAI Evals](https://github.com/openai/evals) compatible format

Privacy levels:
- **anonymous**: Only aggregate metrics (token counts, durations, success rates)
- **full**: Full session data including prompts and responses

## Requirements

- Node.js 18+ or Bun
- AI CLI: [Claude Code](https://github.com/anthropics/claude-code), [OpenCode](https://opencode.ai/docs/), [Cursor](https://cursor.com), Codex, Qwen-Code, [Factory Droid](https://docs.factory.ai/cli/getting-started/quickstart), or [GitHub Copilot](https://docs.github.com/en/copilot)
- `gh` (optional, for GitHub issues / `--create-pr`)
- `playwright` (optional, for visual regression testing - installed automatically as optional dependency)
- `@anthropics/mcp-playwright` (optional, for AI-driven browser testing during development)

## Credits

Ralph-E is based on [ralphy](https://github.com/michaelshimeles/ralphy) by [Michael Shimeles](https://github.com/michaelshimeles), which itself builds on the open-source Ralph project. Ralph-E extends it with integrated Playwright UI/UX validation, visual regression testing, accessibility checks, self-healing tests, and rollback capabilities.

## Links

- [GitHub](https://github.com/rmach816/Ralph-E)
- [npm](https://www.npmjs.com/package/@ralph-e-cli/ralph-e)

## License

MIT