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.

Ralph can be installed three different ways depending on your workflow. Choose the method that works best for you.

​
Prerequisites

Before installing Ralph, you need:
1
Install an AI Coding Tool
2
Amp (Recommended)
# Visit https://ampcode.com for installation
# Then verify:
amp --version
Claude Code
# Install via npm:
npm install -g @anthropic-ai/claude-code

# Verify:
claude --version
3
Install jq
4
Ralph uses jq to parse JSON files:
5
macOS
brew install jq
Ubuntu/Debian
sudo apt-get install jq
Windows (WSL)
sudo apt-get install jq
6
Git Repository
7
Your project must be a git repository. Ralph uses git commits as memory between iterations.
8
# Initialize if needed:
git init
git add .
git commit -m "Initial commit"

​
Installation Options

Option 1

Copy to ProjectBest for single-project use or customization

Option 2

Global SkillsInstall skills once, use across all projects

Option 3

MarketplaceOne-command install via Claude Code

​
Option 1: Copy to Your Project

Best for: Single project use, or when you need to customize the Ralph prompt for your specific project.
Copy Ralph files directly into your project: 
# From your project root
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/

# Copy the prompt template for your AI tool:
cp /path/to/ralph/prompt.md scripts/ralph/prompt.md    # For Amp
# OR
cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md    # For Claude Code

chmod +x scripts/ralph/ralph.sh

​
File Structure

After copying, your project will have: 
your-project/
├── scripts/
│   └── ralph/
│       ├── ralph.sh          # The main loop script
│       ├── prompt.md         # Amp prompt (OR)
│       ├── CLAUDE.md         # Claude Code prompt
│       ├── prd.json          # Created when you convert a PRD
│       ├── progress.txt      # Created on first run
│       └── archive/          # Previous runs stored here
└── tasks/
    └── prd-*.md              # Your PRD files

​
Customizing the Prompt

After copying, you can customize prompt.md or CLAUDE.md for your project:
  • Add project-specific quality check commands
  • Include codebase conventions
  • Add common gotchas for your stack
  • Specify testing requirements
Example customization:
prompt.md
## Quality Checks

Before marking a story complete, run:

1. `npm run typecheck` - Must pass with zero errors
2. `npm run test` - All tests must pass
3. `npm run lint` - No linting errors
4. For UI changes: Verify in browser using dev-browser skill

## Project Conventions

- Use Tailwind CSS for styling (no CSS modules)
- Server actions in `app/actions/` directory
- Database queries use Prisma ORM
- All forms use react-hook-form + zod validation

​
Option 2: Install Skills Globally

Best for: Using Ralph across multiple projects without copying files each time.
Install the PRD and Ralph skills globally so they’re available in any project: 
cp -r /path/to/ralph/skills/prd ~/.config/amp/skills/
cp -r /path/to/ralph/skills/ralph ~/.config/amp/skills/

​
Available Skills

After installation, you have access to: /prd - Generate Product Requirements Documents Automatically triggered when you ask:
  • “create a prd”
  • “write prd for”
  • “plan this feature”
The skill will:
  1. Ask clarifying questions with lettered options
  2. Generate a structured PRD
  3. Save to tasks/prd-[feature-name].md
/ralph - Convert PRDs to JSON Format Automatically triggered when you ask:
  • “convert this prd”
  • “turn into ralph format”
  • “create prd.json”
The skill will:
  1. Read your markdown PRD
  2. Split large stories into right-sized chunks
  3. Order stories by dependencies
  4. Save to scripts/ralph/prd.json

​
Still Need ralph.sh

You still need to copy the ralph.sh script to each project: 
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/
cp /path/to/ralph/prompt.md scripts/ralph/  # or CLAUDE.md
chmod +x scripts/ralph/ralph.sh
But now you can generate PRDs and convert them to JSON from any project without copying the skills.

​
Option 3: Claude Code Marketplace

Best for: Claude Code users who want the fastest installation.
Install Ralph directly from the Claude Code marketplace:

​
Add the Marketplace

/plugin marketplace add snarktank/ralph

​
Install Ralph Skills

/plugin install ralph-skills@ralph-marketplace
That’s it! The PRD and Ralph skills are now available.

​
Using Marketplace Skills

The skills work automatically when you: 
# Just ask naturally:
"create a prd for user authentication"
"write prd for adding comments to posts"
"plan this feature: export to CSV"

# Claude loads the /prd skill automatically

​
Still Need ralph.sh

You still need the ralph.sh script in your project: 
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/
cp /path/to/ralph/CLAUDE.md scripts/ralph/
chmod +x scripts/ralph/ralph.sh

​
Optional: Configure Amp Auto-Handoff

Highly Recommended for Large StoriesAuto-handoff allows Ralph to handle stories that exceed a single context window by automatically creating a fresh instance when context fills up.
Add to ~/.config/amp/settings.json: 
{
  "amp.experimental.autoHandoff": { "context": 90 }
}
This enables automatic handoff when context reaches 90% capacity. When to use:
  • Large refactoring stories
  • Complex features with many files
  • Stories with extensive test coverage

​
Verify Installation

Test that everything works:
1
Test the Skills
2
Amp
amp
# Then type:
Load the prd skill and create a PRD for a simple counter feature
Claude Code
claude
# Then type:
/prd create a PRD for a simple counter feature
3
You should see clarifying questions appear.
4
Check ralph.sh
5
./scripts/ralph/ralph.sh --help
6
You should see usage information (or an error if prd.json doesn’t exist yet, which is fine).
7
Check jq
8
echo '{"test": true}' | jq '.test'
# Should output: true

​
What’s Next?

Quickstart

Create your first autonomous agent loop in 5 minutes

Writing PRDs

Learn how to write effective PRDs for Ralph

How Ralph Works

Understand Ralph’s architecture and iteration cycle

Customizing Prompts

Customize Ralph for your project

​
Key Files Reference

FilePurpose
ralph.shThe bash loop that spawns fresh AI instances
prompt.mdPrompt template for Amp
CLAUDE.mdPrompt template for Claude Code
prd.jsonUser stories with passes status (the task list)
progress.txtAppend-only learnings for future iterations
skills/prd/Skill for generating PRDs
skills/ralph/Skill for converting PRDs to JSON

​
Troubleshooting

Install jq:
# macOS
brew install jq

# Linux
sudo apt-get install jq
Install your AI coding tool:
Check that skills are in the right directory:
ls ~/.claude/skills/
# Should show: prd/ ralph/
Or verify marketplace installation:
/plugin list
Make the script executable:
chmod +x scripts/ralph/ralph.sh

Build docs developers (and LLMs) love

Get started for freeTalk to us