Ralph is an autonomous AI agent loop that runs Cursor CLI repeatedly until all PRD items are complete. Each iteration is a fresh Cursor CLI agent instance with clean context. Memory persists via git history, progress.txt, and prd.json.

Based on Geoffrey Huntley's Ralph pattern.

Read my in-depth article on how I use Ralph

• Cursor CLI or Amp installed and authenticated (at least one)
• jq installed (brew install jq on macOS, choco install jq on Windows)
• A git repository for your project

Ralph supports multiple AI agent backends via the --worker flag:

More workers can be added by extending the worker functions in ralph.sh.

Ralph includes a PowerShell version (ralph.ps1) for native Windows support:

# Run Ralph on Windows (default: cursor worker)
.\ralph.ps1 [max_iterations]

# With explicit worker and iteration count
.\ralph.ps1 -Worker amp -MaxIterations 12

Alternatively, use WSL (Windows Subsystem for Linux) to run ralph.sh.

Copy the ralph files into your project:

macOS/Linux:

# From your project root
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/
cp /path/to/ralph/prompt.md scripts/ralph/
chmod +x scripts/ralph/ralph.sh

Windows (PowerShell):

# From your project root
mkdir -Force scripts\ralph
Copy-Item C:\path\to\ralph\ralph.ps1 scripts\ralph\
Copy-Item C:\path\to\ralph\prompt.md scripts\ralph\

Copy the skills to your Cursor CLI config for use across all projects:

cp -r skills/prd ~/.cursor/skills/
cp -r skills/ralph ~/.cursor/skills/

Note: Cursor CLI automatically handles context management, so no additional configuration is needed.

Copy the ralph_install.sh from copy_to_project/ralph_install.sh

Ralph includes a web-based UI for creating PRDs and converting them to JSON format. This provides a user-friendly alternative to using Cursor CLI skills.

See PRD UI Documentation for setup and usage instructions.

Option A: Using the Web UI (Recommended)

1. Start the PRD UI (see PRD UI Documentation)
2. Navigate to "Create PRD"
3. Select your project directory
4. Follow the guided wizard to create your PRD
5. The PRD will be saved to tasks/prd-[feature-name].md

Option B: Using Cursor CLI Skills

Use the PRD skill to generate a detailed requirements document:

Load the prd skill and create a PRD for [your feature description]

Answer the clarifying questions. The skill saves output to tasks/prd-[feature-name].md.

Option A: Using the Web UI (Recommended)

1. In the PRD UI, navigate to "Convert to JSON"
2. Select your project directory
3. Choose an existing PRD file or paste PRD content
4. Review the generated JSON
5. Save prd.json to your project root

Option B: Using Cursor CLI Skills

Use the Ralph skill to convert the markdown PRD to JSON:

Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json

This creates prd.json with user stories structured for autonomous execution.

# Default: Cursor CLI worker, 10 iterations
./scripts/ralph/ralph.sh

# Specify max iterations
./scripts/ralph/ralph.sh 20

# Use Amp as the worker
./scripts/ralph/ralph.sh --worker amp 15

# Or use short flag
./scripts/ralph/ralph.sh -w amp 15

# Show help
./scripts/ralph/ralph.sh --help

Note: Ralph uses the configured worker agent with --print --force flags to enable shell execution. This allows Ralph to run git commands, quality checks, and commits automatically.

Ralph will:

1. Create a feature branch (from PRD branchName)
2. Pick the highest priority story where passes: false
3. Implement that single story
4. Run quality checks (typecheck, tests)
5. Commit if checks pass
6. Update prd.json to mark story as passes: true
7. Append learnings to progress.txt
8. Repeat until all stories pass or max iterations reached

View Interactive Flowchart - Click through to see each step with animations.

The flowchart/ directory contains the source code. To run locally:

cd flowchart
npm install
npm run dev

Each iteration spawns a new Cursor CLI agent instance with clean context. The only memory between iterations is:

• Git history (commits from previous iterations)
• progress.txt (learnings and context)
• prd.json (which stories are done)

Each PRD item should be small enough to complete in one context window. If a task is too big, the LLM runs out of context before finishing and produces poor code.

Right-sized stories:

• Add a database column and migration
• Add a UI component to an existing page
• Update a server action with new logic
• Add a filter dropdown to a list

Too big (split these):

• "Build the entire dashboard"
• "Add authentication"
• "Refactor the API"

After each iteration, Ralph updates the relevant AGENTS.md files with learnings. This is key because Cursor CLI automatically reads these files, so future iterations (and future human developers) benefit from discovered patterns, gotchas, and conventions.

Examples of what to add to AGENTS.md:

• Patterns discovered ("this codebase uses X for Y")
• Gotchas ("do not forget to update Z when changing W")
• Useful context ("the settings panel is in component X")

Ralph only works if there are feedback loops:

• Typecheck catches type errors
• Tests verify behavior
• CI must stay green (broken code compounds across iterations)

Frontend stories must include "Verify in browser using dev-browser skill" in acceptance criteria. Ralph will use the dev-browser skill to navigate to the page, interact with the UI, and confirm changes work.

When all stories have passes: true, Ralph outputs <promise>COMPLETE</promise> and the loop exits.

Check current state:

# See which stories are done
cat prd.json | jq '.userStories[] | {id, title, passes}'

# See learnings from previous iterations
cat progress.txt

# Check git history
git log --oneline -10

Shell execution unavailable error:

• Ensure your chosen worker is installed and authenticated
  • Cursor CLI: agent --version and agent status
  • Amp: amp --version
• Verify ralph.sh uses --print --force flags (should be automatic)
• Check that the agent command is in your PATH
• The script automatically checks for required commands on startup

Agent command not found:

• For Cursor CLI: Install from https://cursor.com/docs/cli, then verify with agent --version
• For Amp: Install from https://ampcode.com, then verify with amp --version
• Ensure the command is in your PATH
• Test the command: agent --print --force --output-format text "Test" or amp --yes --print "Test"

PRD generation or JSON conversion fails in PRD UI:

• Check that Cursor CLI agent is available and authenticated
• The PRD UI uses spawn for reliable agent command execution
• Agent output is automatically parsed (handles wrapped JSON, markdown code fences, etc.)
• The UI automatically falls back to template-based methods if agent fails
• See PRD UI Documentation for detailed troubleshooting

jq command not found:

• Install jq: brew install jq (macOS) or see https://stedolan.github.io/jq/download/
• Verify installation: jq --version

Edit prompt.md to customize Ralph's behavior for your project:

• Add project-specific quality check commands
• Include codebase conventions
• Add common gotchas for your stack

Ralph automatically archives previous runs when you start a new feature (different branchName). Archives are saved to archive/YYYY-MM-DD-feature-name/.

Ralph includes a full-stack web application for creating and managing PRDs through a user-friendly interface. The PRD UI provides:

• Guided PRD Creation: Multi-step wizard with intelligent question generation
• PRD to JSON Conversion: Convert markdown PRDs to Ralph's JSON format
• Cursor CLI Integration: Uses Cursor CLI agent for enhanced generation (with template fallback)
• Project Management: Point to any project directory to manage PRDs
• Real-time Preview: See PRD markdown and JSON previews as you work

• Uses Node.js spawn for reliable agent command execution (no shell escaping issues)
• Handles agent output formats (wrapped JSON, markdown code fences, etc.)
• Automatic fallback to template-based methods if agent unavailable
• Comprehensive test suite with unit and integration tests

See the PRD UI Documentation for detailed setup and usage instructions.

• Geoffrey Huntley's Ralph article
• Cursor CLI documentation