Getting Started

What This Workshop Covers

Ralph is a technique for running AI coding agents in a loop. You give it a PRD. It picks tasks, implements them, and commits. You come back to working code.

By the end, you'll know how to:

• Run Ralph in HITL (human-in-the-loop) and AFK modes
• Steer Ralph toward better outputs
• Build feedback loops that catch errors early
• Connect Ralph to your backlog
• Write PRDs that Ralph executes well

Workshop Ethics

• All questions are good questions
• Bring an open mind
• Be ready to work in teams

Prerequisites

You need a subscription to Claude Code or OpenCode. I'll be running Claude Code. AFK Ralph requires Claude Code.

Setup

There are two ways to run Ralph:

• HITL (Human-in-the-loop) — Minimal setup, recommended for learning
• AFK — Production-ready, requires more setup

The default for this workshop is HITL (Human-in-the-loop) Ralph. It requires no extra setup and is the best way to learn Ralph and refine your prompts.

You're welcome to run AFK Ralph during the workshop. If you hit setup issues, fall back to HITL Ralph.

AFK Ralph

AFK Ralph is what you'd run in production. It's optional for the workshop. If you want to run it, here are some setup instructions:

Platform: macOS or Linux/WSL. Windows/PowerShell not supported.

Requirements:

1. Node via nvm

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
nvm install --lts

nvm GitHub

2. GitHub CLI

brew install gh
gh auth login

GitHub CLI manual

3. Claude Code

curl -fsSL https://claude.ai/install.sh | bash

Claude Code setup docs

4. Docker Desktop with Sandboxes

Install Docker Desktop 4.50+. Enable Docker Sandboxes in settings.

Docker Sandboxes docs

5. jq

brew install jq

jq download page

Repositories

Clone these repos and fetch all branches for the workshop.

One-liner:

for repo in ralph-workshop-repo-002 ralph-workshop-repo-001; do git clone "https://github.com/mattpocock/$repo.git" && cd "$repo" && for branch in $(git branch -r | grep -v '\->'); do git branch --track "${branch#origin/}" "$branch" 2>/dev/null || true; done && cd ..; done

Step-by-step:

# Clone the first repo
git clone "https://github.com/mattpocock/ralph-workshop-repo-001.git"
cd ralph-workshop-repo-001
# Fetch all remote branches
for branch in $(git branch -r | grep -v '\->'); do git branch --track "${branch#origin/}" "$branch" 2>/dev/null || true; done
cd ..

# Clone the second repo
git clone "https://github.com/mattpocock/ralph-workshop-repo-002.git"
cd ralph-workshop-repo-002
# Fetch all remote branches
for branch in $(git branch -r | grep -v '\->'); do git branch --track "${branch#origin/}" "$branch" 2>/dev/null || true; done
cd ..