Skip to content

mesolimbo/ralph

BranchesTags

Repository files navigation

Ralph

Ralph - Dockerized Claude in Unrestricted Mode

What is the Ralph Technique?

Ralph is an AI-assisted software development technique created by Geoffrey Huntley. At its core, it's a bash loop that repeatedly pipes a prompt into Claude Code:

while :; do cat PROMPT.md | claude ; done

The idea is iterative refinement through eventual consistency — rather than crafting a single perfect prompt, you run the same instructions in a loop and let the AI incrementally build, fix, and improve the codebase over multiple passes. When results aren't right, you tune the prompt — "like tuning a guitar" — instead of blaming the tools.

This project packages that loop into a Docker container with full permissions so you can point it at a workspace and let it run a set number of times (or indefinitely).

Features

  • TUI launcher — a standalone binary (ralph) that can be run from anywhere, with an interactive UI for configuring workspaces and auth keys
  • Secure credential storage — auth keys are stored in the OS keychain (macOS Keychain / Windows Credential Manager) via the keyring library, not in plaintext .env files
  • Dockerized loop — runs Claude CLI with --dangerously-skip-permissions and full sudo, so no prompts interrupt the cycle
  • Auto-exit hook — a container hook (stop-and-exit.sh) terminates Claude at the end of each pass so the loop can restart cleanly
  • Configurable iterations — run indefinitely or set a cap with -i
  • 10 custom subagents — the container ships with a full SDLC team defined in .claude/agents/: Product Manager, Software Architect, Software Developer, UX Designer, QA Engineer, Security Engineer, Performance Engineer, DevOps Engineer, Release Manager, and Technical Writer
  • Ready-made prompt template — .ralph/prompt.md.template is preconfigured to orchestrate those agents iteratively: break a goal into tasks, delegate each task to the right subagent one at a time, track progress in .ralph/, and loop back for review and cleanup
  • Example SDLC archives — docs/.ralph/Archives/ contains full examples (a Minesweeper game, an interactive agent inventory chart, and a marketing pitch) complete with requirements, architecture docs, QA reports, security audits, and final status write-ups
  • Dual auth — supports both OAuth tokens and API keys (OAuth takes priority)

Playwright MCP Integration

The container includes Playwright MCP, Microsoft's official Model Context Protocol server for browser automation. It gives agents the ability to navigate web pages, interact with UI elements, inspect the accessibility tree, and run JavaScript in a real browser -- all through structured tool calls rather than fragile shell commands.

Which Agents Have Access

Five of the ten subagents are configured with Playwright tools:

Agent Primary Use
QA Engineer E2E testing, regression testing, accessibility audits, test assertion and locator generation
UX Designer Accessibility tree inspection, keyboard navigation testing, responsive layout validation
Software Developer Feature verification, front-end debugging, E2E test code generation
Security Engineer Client-side vulnerability testing (XSS, CSRF), security header inspection, session analysis
Performance Engineer Page load measurement, network waterfall analysis, resource loading verification

The remaining agents (Product Manager, Software Architect, DevOps Engineer, Release Manager, Technical Writer) do not have Playwright access because their workflows do not require browser interaction.

Key Capabilities

  • Accessibility snapshots -- structured text representations of the page DOM (2-5 KB), used instead of screenshots for faster, more token-efficient page inspection
  • Browser interaction -- click, type, fill forms, select options, drag, press keys, handle dialogs
  • Page inspection -- accessibility tree snapshots, screenshots, console messages, network request logs
  • JavaScript execution -- run arbitrary JS or Playwright code snippets in the page context
  • Testing assertions -- verify element visibility, text content, and input values (QA Engineer and Software Developer only)

Headless Environment

Playwright runs in headless Chromium mode inside the container. The configuration lives in .mcp.json at the project root:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless", "--enable-testing"]
    }
  }
}

The Docker image uses Alpine's system Chromium (compiled for musl libc) rather than Playwright's default glibc-based download. The Dockerfile handles all browser dependencies automatically -- no additional setup is required.

Usage Examples

Below are practical examples showing how to write goals in .ralph/prompt.md that leverage Playwright capabilities through the appropriate subagents.

Example 1: QA Engineer -- End-to-end form testing

Your goal is to thoroughly test the signup form at app/signup.html.
Open the form in the browser, fill in each field with valid and invalid data,
submit the form, and verify that validation messages, success states, and
error handling all work correctly. Document any defects found in .ralph/qa-report.md.

Ralph delegates this to the qa-engineer agent, which uses browser_navigate to load the form, browser_fill_form and browser_click to submit it with various inputs, and browser_verify_text_visible to assert that the correct validation messages appear. The agent also checks browser_console_messages for JavaScript errors after each submission.

Example 2: UX Designer -- Accessibility audit

Your goal is to audit the dashboard page at app/dashboard.html for
WCAG 2.1 AA compliance. Inspect the accessibility tree, test keyboard navigation
through all interactive elements, and verify the page is usable at mobile,
tablet, and desktop viewport widths. Write your findings to .ralph/ux-design.md.

Ralph delegates this to the ux-designer agent, which uses browser_snapshot to examine the accessibility tree for missing labels, roles, and ARIA attributes, then browser_press_key to Tab through every interactive element and confirm focus order. It calls browser_resize at 375px, 768px, and 1280px widths to verify the responsive layout does not break.

Example 3: Software Developer -- Feature verification and E2E test generation

Your goal is to verify that the dark mode toggle on app/index.html
works correctly, then generate a Playwright E2E test file that covers the toggle
behavior. The test should assert that the body class changes, stored preference
persists on reload, and no console errors occur. Save the test to
tests/e2e/dark-mode.spec.ts

Ralph delegates this to the software-developer agent, which uses browser_navigate to load the page, browser_click to activate the toggle, and browser_snapshot to confirm the DOM reflects dark mode. It checks browser_console_messages for errors, then uses browser_generate_locator to produce stable selectors and writes a complete Playwright test file with proper assertions.

Quick Start

1. Build the Docker image

make build

2. Build the TUI launcher

make binary

This produces a standalone binary at dist/ralph-<version>/ralph (or ralph.exe on Windows). Move it somewhere on your PATH:

# macOS / Linux
sudo mv dist/ralph-*/ralph /usr/local/bin/

# Windows — move dist/ralph-*/ralph.exe to a directory on your PATH

3. Configure auth keys

Run ralph with no arguments. On first launch it opens the Settings tab where you can enter your credentials:

  • OAuth token (recommended) — generate with claude setup-token
  • API key — from the Anthropic console

Keys are stored securely in your OS keychain, not in plaintext files.

4. Set up a workspace

mkdir -p /path/to/your/project/.ralph
cp .ralph/prompt.md.template /path/to/your/project/.ralph/prompt.md
# Edit prompt.md with your goal

5. Run

# Interactive TUI — configure workspace and run
ralph

# Run directly with a workspace path
ralph /path/to/your/project

# With an iteration limit
ralph /path/to/your/project -i 5

Usage

TUI Launcher (recommended)

ralph                              # Open interactive TUI
ralph /path/to/workspace           # Pre-fill workspace and auto-run
ralph /path/to/workspace -i 5      # Auto-run with iteration cap
ralph -v                           # Show version

The TUI has two tabs:

  • Run — set workspace path, iteration limit, and launch
  • Settings — manage auth keys stored in the OS keychain

Makefile (alternative)

The Makefile still works for users who prefer it:

# Copy .env.template to .env and set auth credentials
cp .env.template .env

make build                                     # Build Docker image
make test                                      # Run tests
make ralph WORKSPACE=/path/to/workspace        # Run with mounted workspace
make ralph WORKSPACE=./myproject MAX_ITERATIONS=5
make binary                                    # Build standalone TUI binary
make clean                                     # Remove Docker images

Options

Option Description Default
Workspace path Directory to mount as /workspace (must contain .ralph/prompt.md) . (current directory)
Iterations (-i) Maximum loop iterations (0 = unlimited) 0

How It Works

  1. The container mounts your workspace directory to /workspace
  2. On each iteration, it reads .ralph/prompt.md and pipes it to Claude
  3. Claude runs with --dangerously-skip-permissions (no tool restrictions)
  4. The loop continues until the iteration limit is reached (or forever if 0)

Prompt File

Create a .ralph/prompt.md file in your workspace directory with instructions for Claude:

mkdir -p /path/to/your/project/.ralph
cp .ralph/prompt.md.template /path/to/your/project/.ralph/prompt.md
# Edit the file with your instructions

The included template (.ralph/prompt.md.template) sets up an agent-driven SDLC workflow out of the box. You insert your goal at the top, and Ralph will:

  1. Break the goal into granular tasks
  2. Delegate each task to the most appropriate subagent (e.g. software-developer, qa-engineer)
  3. Track progress in .ralph/ markdown files
  4. Run review and cleanup passes after all tasks complete
  5. On the next iteration, pick up where it left off or find incremental improvements

The docs/ directory contains worked examples that were built entirely by Ralph. Browse them all at mesolimbo.github.io/ralph. Highlights:

Example Description
Minesweeper Retro Windows 95-style game — single HTML file, zero dependencies, ~650 LOC
Agent Inventory Interactive orbital chart of the 10 SDLC agents with filtering and dark mode
freelance.ai Landing Page Demo marketing page for a fictional SaaS product

Full SDLC archives for each (requirements, architecture, QA reports, security audits, etc.) live in docs/.ralph/Archives/.

Security Warning

This container runs Claude with no permission restrictions and full sudo access. Only use it:

  • In isolated environments
  • With trusted prompt files
  • On non-sensitive codebases
  • Use at your own risk

Requirements

  • Docker — for building and running the container
  • Python 3.13 + pipenv — only needed to build the TUI binary (make binary)
  • Authentication via one of:
    • OAuth token (generate with claude setup-token)
    • API key from the Anthropic console
  • If both are set, OAuth token takes priority

About

A dockerized environment in which to run Claude Code in Ralph Wigggum mode

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages