Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/snarktank/ralph/llms.txt

Use this file to discover all available pages before exploring further.

Get Ralph running on your project in just a few minutes. This guide will walk you through creating your first autonomous AI agent loop.

​
What You’ll Build

By the end of this quickstart, you’ll have:
  • Ralph installed in your project
  • A sample PRD converted to JSON format
  • Ralph running autonomously to implement features
1
Prerequisites Check
2
Before starting, ensure you have:
3
Amp (Default)
# Check if Amp is installed
amp --version

# If not installed, visit:
# https://ampcode.com
Claude Code
# Check if Claude Code is installed
claude --version

# If not installed:
npm install -g @anthropic-ai/claude-code
4
You’ll also need:
5
  • jq installed (brew install jq on macOS)
  • A git repository for your project
    • 6
    Copy Ralph Files
    7
    From your project root, copy Ralph into your project:
    8
    mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/

# For Amp (default):
cp /path/to/ralph/prompt.md scripts/ralph/prompt.md

# OR for Claude Code:
cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md

chmod +x scripts/ralph/ralph.sh
    9
    Choose either prompt.md (for Amp) or CLAUDE.md (for Claude Code) based on which AI tool you’re using.
    10
    Create Your First PRD
    11
    If you installed the Ralph skills globally or via Claude Code marketplace, you can use the PRD skill:
    12
    Amp
    amp
# Then type: Load the prd skill and create a PRD for a task priority system
    Claude Code
    claude
# Then type: /prd create a PRD for a task priority system
    13
    The skill will:
    14
  • Ask 3-5 clarifying questions with lettered options (answer like “1A, 2C, 3B”)
  • Generate a structured PRD
  • Save it to tasks/prd-task-priority.md
    • 15
    Each user story should be small enough to complete in one context window. If a task is too big, the AI runs out of context before finishing.
    16
    Example of right-sized stories:
    17
  • Add a database column and migration
  • Add a UI component to an existing page
  • Update a server action with new logic
    • 18
    Too big (split these):
    19
  • “Build the entire dashboard”
  • “Add authentication”
  • “Refactor the API”
    • 20
    Convert PRD to JSON
    21
    Use the Ralph skill to convert your markdown PRD to the JSON format Ralph needs:
    22
    Amp
    amp
# Then type: Load the ralph skill and convert tasks/prd-task-priority.md to prd.json
    Claude Code
    claude
# Then type: /ralph convert tasks/prd-task-priority.md to prd.json
    23
    This creates scripts/ralph/prd.json with your user stories structured like:
    24
    {
  "project": "TaskApp",
  "branchName": "ralph/task-priority",
  "description": "Add priority levels to tasks",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add priority field to database",
      "description": "As a developer, I need to store task priority.",
      "acceptanceCriteria": [
        "Add priority column to tasks table",
        "Generate and run migration successfully",
        "Typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}
    25
    Run Ralph
    26
    Now start the autonomous loop:
    27
    Amp (Default)
    ./scripts/ralph/ralph.sh

# Or specify max iterations (default is 10):
./scripts/ralph/ralph.sh 20
    Claude Code
    ./scripts/ralph/ralph.sh --tool claude

# Or specify max iterations:
./scripts/ralph/ralph.sh --tool claude 20
    28
    Ralph will now:
    29
  • Create a feature branch (from PRD branchName)
  • Pick the highest priority story where passes: false
  • Implement that single story
  • Run quality checks (typecheck, tests)
  • Commit if checks pass
  • Update prd.json to mark story as passes: true
  • Append learnings to progress.txt
  • Repeat until all stories pass or max iterations reached
    • 30
    Each iteration spawns a fresh AI instance with clean context. Memory persists only via:
    • Git history (commits from previous iterations)
    • progress.txt (learnings and context)
    • prd.json (which stories are complete)
    31
    Verify Results
    32
    Check Ralph’s progress at any time:
    33
    # See which stories are complete
cat scripts/ralph/prd.json | jq '.userStories[] | {id, title, passes}'

# View learnings from iterations
cat scripts/ralph/progress.txt

# Check git history
git log --oneline -10
    34
    When all stories have passes: true, Ralph outputs <promise>COMPLETE</promise> and exits.

    ​
    What’s Next?

    Installation Options

    Explore all installation methods

    How Ralph Works

    Learn about the autonomous loop

    Writing PRDs

    Master the PRD skill

    Troubleshooting

    Debug common issues

    ​
    Key Concepts to Remember

    Each Iteration = Fresh ContextRalph spawns a new AI instance for each iteration with zero memory of previous work. This is why:
    • Stories must be small enough to complete in one context window
    • progress.txt and AGENTS.md updates are critical
    • Git commits are your memory
    Feedback Loops Are EssentialRalph only works with automated quality checks:
    • Typecheck catches type errors
    • Tests verify behavior
    • CI must stay green (broken code compounds across iterations)
    For UI Stories: Always include “Verify in browser using dev-browser skill” in acceptance criteria. Ralph will use the dev-browser skill to visually confirm changes work.

    Build docs developers (and LLMs) love

    Get started for freeTalk to us