Installation

Install Ralph using project-local files, global skills, or Claude Code marketplace

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 Project

Best for single-project use or customization

Option 2

Global Skills

Install skills once, use across all projects

Option 3

Marketplace

One-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:

Amp

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:

Generate a PRD

# 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 Stories

Auto-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

File	Purpose
ralph.sh	The bash loop that spawns fresh AI instances
prompt.md	Prompt template for Amp
CLAUDE.md	Prompt template for Claude Code
prd.json	User stories with passes status (the task list)
progress.txt	Append-only learnings for future iterations
skills/prd/	Skill for generating PRDs
skills/ralph/	Skill for converting PRDs to JSON

Troubleshooting

Error: jq command not found

Install jq:

# macOS
brew install jq

# Linux
sudo apt-get install jq

Error: amp/claude command not found

Install your AI coding tool:

• Amp: Visit https://ampcode.com
• Claude Code: npm install -g @anthropic-ai/claude-code

Skills not loading in Claude Code

Check that skills are in the right directory:

ls ~/.claude/skills/
# Should show: prd/ ralph/

Or verify marketplace installation:

/plugin list

Permission denied when running ralph.sh

Make the script executable:

chmod +x scripts/ralph/ralph.sh