ddev-ralph

A DDEV add-on that provides Ralph Loop, an autonomous AI task orchestrator for Drupal development. Ralph delegates work to OpenCode or Claude Code containers via SSH, running AI agents in a loop with Beads task tracking. Perfect for overnight unattended execution.

Part of DDEV AI Workspace — a modular ecosystem of DDEV add-ons for AI-powered Drupal development. Install the full stack with one command: ddev add-on get trebormc/ddev-ai-workspace

Created by Robert Menetray · Sponsored by DruScan

Important: Ralph is a lightweight orchestrator. It does not include AI tools itself. You must have at least one backend installed first:

• ddev-opencode for the OpenCode backend
• ddev-claude-code for the Claude Code backend

Quick Start

The recommended way to install Ralph is through the DDEV AI Workspace, which installs all tools (Ralph, OpenCode, Claude Code, and all dependencies) with a single command:

ddev add-on get trebormc/ddev-ai-workspace
ddev restart
ddev ralph --backend opencode

Standalone installation

If you prefer to install Ralph individually, you need at least one AI backend installed first. This requires familiarity with the DDEV add-on ecosystem and its dependencies:

# 1. Install a backend (pick one or both)
ddev add-on get trebormc/ddev-opencode
# or
ddev add-on get trebormc/ddev-claude-code

# 2. Install Ralph (auto-installs ddev-playwright-mcp and ddev-beads)
ddev add-on get trebormc/ddev-ralph
ddev restart

Example: run Ralph with a requirements file

cat > requirements.md << 'EOF'
# My Feature

## Objective
Create a custom Drupal module that does X.

## Requirements
- Feature A with admin form
- Feature B with tests

## Success Criteria
- PHPUnit tests passing
- PHPStan level 8 clean
- PHPCS no errors
EOF

ddev ralph --backend opencode

Usage

# Run with OpenCode backend
ddev ralph --backend opencode

# Run with Claude Code backend
ddev ralph --backend claude

# Custom requirements file
ddev ralph --backend opencode --prompt my-tasks.md

# Resume existing tasks (skip the planning phase)
ddev ralph --backend claude --no-replan

# Override model
ddev ralph --backend opencode -m anthropic/claude-sonnet-4-6

# Maximum speed overnight run
ddev ralph --backend claude -i 500 -d 0

# Open shell in Ralph container
ddev ralph shell

How It Works

┌──────────────────────────────────────────────────────┐
│  PLANNING PHASE (Iteration 1)                        │
│    Read requirements.md -> Create tasks with bd      │
│    Signal: PLANNING_COMPLETE                         │
│                                                      │
│  EXECUTION PHASE (Iterations 2+)                     │
│    bd ready -> Work on task -> bd close              │
│    Repeat until all tasks done                       │
│                                                      │
│  EXIT: When bd ready returns []                      │
└──────────────────────────────────────────────────────┘

1. Planning: Ralph reads your requirements.md and creates a set of Beads tasks.
2. Execution: Each iteration picks the next ready task, delegates it to the AI backend, and closes it when done.
3. Completion: When no more tasks remain, Ralph exits.

Options

Requirements File Format

The requirements.md file tells Ralph what to build. Structure it with clear objectives, requirements, and success criteria:

# Project Title

## Objective
One paragraph describing what needs to be built.

## Requirements
- Specific feature or task (be concrete)
- Another feature with details
- Include technical constraints

## Technical Constraints
- Drupal 10/11 compatible
- PHP 8.1+ with strict types
- Drupal coding standards (PHPCS)
- PHPStan level 8

## Success Criteria
- All PHPUnit tests pass
- PHPCS reports no errors
- PHPStan level 8 clean
- Module enables without errors

See .ddev/ralph-loop/requirements-example.md for a complete example after installation.

Audit Fixers

Ralph ships with pre-built requirements files for common code quality fixes. These are ideal for automated cleanup runs:

# Fix PHPCS coding standard violations
ddev ralph --backend opencode --prompt .ddev/ralph-loop/audit-fixers/fix-phpcs.md

# Fix PHPStan static analysis issues
ddev ralph --backend claude --prompt .ddev/ralph-loop/audit-fixers/fix-phpstan.md

# Fix Twig template issues
ddev ralph --backend claude --prompt .ddev/ralph-loop/audit-fixers/fix-twig.md

# Fix code complexity issues
ddev ralph --backend opencode --prompt .ddev/ralph-loop/audit-fixers/fix-complexity.md

Test Generation

Ralph includes prompts for automated test generation across all Drupal test types. Two modes of operation:

Orchestrator Mode

Analyzes the entire project, detects which test types are missing for each module, and generates them all in a single run:

ddev ralph --backend claude --prompt .ddev/ralph-loop/audit-fixers/generate-tests.md

The orchestrator creates Beads tasks ordered by priority: Kernel tests (P0), Unit and Functional tests (P1), FunctionalJavascript (P2), Behat/Playwright (P3). It skips test types that do not apply (e.g., no Behat if the project has no behat.yml).

Direct Mode

Run a specific test type when you know exactly what you need:

# Unit tests — pure PHP logic, mocked dependencies (uses Audit module)
ddev ralph --backend claude --prompt .ddev/ralph-loop/audit-fixers/generate-unit-tests.md

# Kernel tests — services, entities, DB, config, plugins, hooks (most valuable)
ddev ralph --backend claude --prompt .ddev/ralph-loop/audit-fixers/generate-kernel-tests.md

# Functional tests — forms, permissions, HTML output
ddev ralph --backend claude --prompt .ddev/ralph-loop/audit-fixers/generate-functional-tests.md

# FunctionalJavascript tests — AJAX, modals, autocompletes
ddev ralph --backend claude --prompt .ddev/ralph-loop/audit-fixers/generate-functionaljs-tests.md

# Behat tests — BDD acceptance testing in Gherkin (requires behat.yml)
ddev ralph --backend claude --prompt .ddev/ralph-loop/audit-fixers/generate-behat-tests.md

# Playwright tests — visual regression, cross-browser, accessibility, E2E
ddev ralph --backend claude --prompt .ddev/ralph-loop/audit-fixers/generate-playwright-tests.md

All test generation prompts reference the specialized skills from drupal-ai-agents (drupal-unit-test, drupal-kernel-test, drupal-functional-test, etc.) and follow the drupal-testing decision rule for choosing the correct test type per class.

Architecture

┌──────────────────────────────────────────────────────────┐
│                    DDEV Docker Network                    │
│                                                          │
│  ┌─────────────┐                                         │
│  │   Ralph     │     SSH          ┌──────────────┐      │
│  │ (orchestr.) │─────────────────>│  OpenCode    │      │
│  │             │       OR         │  Container   │      │
│  │ bash + jq   │─────────────────>│──────────────│      │
│  │ SSH client  │                  │ Claude Code  │      │
│  │             │                  │  Container   │      │
│  └─────────────┘                  └──────────────┘      │
│        │                                │                │
│        │ SSH                            │ SSH            │
│        v                                v                │
│   ┌──────────┐                   ┌──────────────┐       │
│   │  Beads   │                   │     Web      │       │
│   │ Container│                   │   (PHP)      │       │
│   │ (.beads) │                   └──────────────┘       │
│   └──────────┘                                          │
│                                  ┌──────────────┐       │
│                                  │  Playwright  │       │
│                                  │     MCP      │       │
│                                  └──────────────┘       │
└──────────────────────────────────────────────────────────┘

Ralph only contains bash, jq, and an SSH client. All AI execution happens in the dedicated OpenCode or Claude Code containers, and task tracking runs in the Beads container (all via SSH). SSH keys are auto-generated per project in .ddev/.agent-ssh-keys/. This keeps each component independently maintainable.

Exit Codes

Uninstallation

ddev add-on remove ddev-ralph
ddev restart

Part of DDEV AI Workspace

This add-on is part of DDEV AI Workspace, a modular ecosystem of DDEV add-ons for AI-powered Drupal development.

Disclaimer

This project is an independent initiative by Robert Menetray, sponsored by DruScan. It is not affiliated with Anthropic, OpenCode, Beads, Playwright, Microsoft, or DDEV. AI-generated code may contain errors. Always review changes before deploying to production.

License

Apache-2.0. See LICENSE.