ralph-marketplace
Ralph is an autonomous AI agent loop that runs repeatedly until all PRD items are complete.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/snarktank-ralph)HTML
<a href="/listings/snarktank-ralph"><img src="/api/listings/snarktank-ralph/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Option 1: Copy to your project
Copy the ralph files 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 of choice: 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
Option 2: Install skills globally (Amp)
Copy the skills to your Amp or Claude config for use across all projects:
For AMP
cp -r skills/prd ~/.config/amp/skills/ cp -r skills/ralph ~/.config/amp/skills/
For Claude Code (manual)
cp -r skills/prd ~/.claude/skills/ cp -r skills/ralph ~/.claude/skills/
Option 3: Use as Claude Code Marketplace
Add the Ralph marketplace to Claude Code:
/plugin marketplace add snarktank/ralph
Then install the skills:
/plugin install ralph-skills@ralph-marketplace
Available skills after installation: - `/prd` - Generate Product Requirements Documents - `/ralph` - Convert PRDs to prd.json format
Skills are automatically invoked when you ask Claude to: - "create a prd", "write prd for", "plan this feature" - "convert this prd", "turn into ralph format", "create prd.json"
Configure Amp auto-handoff (recommended)
Add to `~/.config/amp/settings.json`:
{
"amp.experimental.autoHandoff": { "context": 90 }
}This enables automatic handoff when context fills up, allowing Ralph to handle large stories that exceed a single context window.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 21 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "name": "ralph-marketplace",
- "owner": {
- "name": "snarktank"
- },
- "metadata": {
- "description": "Skills for the Ralph autonomous agent system - Generate PRDs and convert them to prd.json format for autonomous execution",
- "version": "1.0.0"
- },
- "plugins": [
- {
- "name": "ralph-skills",
- "source": "./",
- "description": "PRD generation and conversion skills for the Ralph autonomous agent loop",
- "version": "1.0.0",
- "keywords": ["ralph", "prd", "automation", "agent", "planning"],
- "category": "productivity",
- "skills": "./skills/"
- }
- ]
- }
README.md · README · 239 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Ralph
- 
- Ralph is an autonomous AI agent loop that runs AI coding tools ([Amp](https://ampcode.com) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code)) repeatedly until all PRD items are complete. Each iteration is a fresh instance with clean context. Memory persists via git history, `progress.txt`, and `prd.json`.
- Based on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/).
- [Read my in-depth article on how I use Ralph](https://x.com/ryancarson/status/2008548371712135632)
- ## Prerequisites
- - One of the following AI coding tools installed and authenticated:
- - [Amp CLI](https://ampcode.com) (default)
- - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`npm install -g @anthropic-ai/claude-code`)
- - `jq` installed (`brew install jq` on macOS)
- - A git repository for your project
- ## Setup
- ### Option 1: Copy to your project
- Copy the ralph files into your project:
- ```bash
- # From your project root
- mkdir -p scripts/ralph
- cp /path/to/ralph/ralph.sh scripts/ralph/
- # Copy the prompt template for your AI tool of choice:
- 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
- ```
- ### Option 2: Install skills globally (Amp)
- Copy the skills to your Amp or Claude config for use across all projects:
- For AMP
- ```bash
- cp -r skills/prd ~/.config/amp/skills/
- cp -r skills/ralph ~/.config/amp/skills/
- ```
- For Claude Code (manual)
- ```bash
- cp -r skills/prd ~/.claude/skills/
- cp -r skills/ralph ~/.claude/skills/
- ```
- ### Option 3: Use as Claude Code Marketplace
- Add the Ralph marketplace to Claude Code:
- ```bash
- /plugin marketplace add snarktank/ralph
- ```
- Then install the skills:
- ```bash
- /plugin install ralph-skills@ralph-marketplace
- ```
- Available skills after installation:
- - `/prd` - Generate Product Requirements Documents
- - `/ralph` - Convert PRDs to prd.json format
- Skills are automatically invoked when you ask Claude to:
- - "create a prd", "write prd for", "plan this feature"
- - "convert this prd", "turn into ralph format", "create prd.json"
- ### Configure Amp auto-handoff (recommended)
- Add to `~/.config/amp/settings.json`:
- ```json
- {
- "amp.experimental.autoHandoff": { "context": 90 }
- }
- ```
- This enables automatic handoff when context fills up, allowing Ralph to handle large stories that exceed a single context window.
- ## Workflow
- ### 1. Create a PRD
- 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`.
- ### 2. Convert PRD to Ralph format
- 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.
- ### 3. Run Ralph
- ```bash
- # Using Amp (default)
- ./scripts/ralph/ralph.sh [max_iterations]
- # Using Claude Code
- ./scripts/ralph/ralph.sh --tool claude [max_iterations]
- ```
- Default is 10 iterations. Use `--tool amp` or `--tool claude` to select your AI coding tool.
- 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
- ## Key Files
- | File | Purpose |
- |------|---------|
- | `ralph.sh` | The bash loop that spawns fresh AI instances (supports `--tool amp` or `--tool claude`) |
- | `prompt.md` | Prompt template for Amp |
- | `CLAUDE.md` | Prompt template for Claude Code |
- | `prd.json` | User stories with `passes` status (the task list) |
- | `prd.json.example` | Example PRD format for reference |
- | `progress.txt` | Append-only learnings for future iterations |
- | `skills/prd/` | Skill for generating PRDs (works with Amp and Claude Code) |
- | `skills/ralph/` | Skill for converting PRDs to JSON (works with Amp and Claude Code) |
- | `.claude-plugin/` | Plugin manifest for Claude Code marketplace discovery |
- | `flowchart/` | Interactive visualization of how Ralph works |
- ## Flowchart
- [](https://snarktank.github.io/ralph/)
- **[View Interactive Flowchart](https://snarktank.github.io/ralph/)** - Click through to see each step with animations.
- The `flowchart/` directory contains the source code. To run locally:
- ```bash
- cd flowchart
- npm install
- npm run dev
- ```
- ## Critical Concepts
- ### Each Iteration = Fresh Context
- Each iteration spawns a **new AI instance** (Amp or Claude Code) 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)
- ### Small Tasks
- 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"
- ### AGENTS.md Updates Are Critical
- After each iteration, Ralph updates the relevant `AGENTS.md` files with learnings. This is key because AI coding tools automatically read 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")
- ### Feedback Loops
- Ralph only works if there are feedback loops:
- - Typecheck catches type errors
- - Tests verify behavior
- - CI must stay green (broken code compounds across iterations)
- ### Browser Verification for UI Stories
- 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.
- ### Stop Condition
- When all stories have `passes: true`, Ralph outputs `<promise>COMPLETE</promise>` and the loop exits.
- ## Debugging
- Check current state:
- ```bash
- # 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
- ```
- ## Customizing the Prompt
- After copying `prompt.md` (for Amp) or `CLAUDE.md` (for Claude Code) to your project, customize it for your project:
- - Add project-specific quality check commands
- - Include codebase conventions
- - Add common gotchas for your stack
- ## Archiving
- Ralph automatically archives previous runs when you start a new feature (different `branchName`). Archives are saved to `archive/YYYY-MM-DD-feature-name/`.
- ## References
- - [Geoffrey Huntley's Ralph article](https://ghuntley.com/ralph/)
- - [Amp documentation](https://ampcode.com/manual)
- - [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code)
ralph.sh · Bundled script · 113 lines · 2 findings marked
- #!/bin/bash
- # Ralph Wiggum - Long-running AI agent loop
- # Usage: ./ralph.sh [--tool amp|claude] [max_iterations]
- set -e
- # Parse arguments
- TOOL="amp" # Default to amp for backwards compatibility
- MAX_ITERATIONS=10
- while [[ $# -gt 0 ]]; do
- case $1 in
- --tool)
- TOOL="$2"
- shift 2
- ;;
- --tool=*)
- TOOL="${1#*=}"
- shift
- ;;
- *)
- # Assume it's max_iterations if it's a number
- if [[ "$1" =~ ^[0-9]+$ ]]; then
- MAX_ITERATIONS="$1"
- fi
- shift
- ;;
- esac
- done
- # Validate tool choice
- if [[ "$TOOL" != "amp" && "$TOOL" != "claude" ]]; then
- echo "Error: Invalid tool '$TOOL'. Must be 'amp' or 'claude'."
- exit 1
- fi
- SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
- PRD_FILE="$SCRIPT_DIR/prd.json"
- PROGRESS_FILE="$SCRIPT_DIR/progress.txt"
- ARCHIVE_DIR="$SCRIPT_DIR/archive"
- LAST_BRANCH_FILE="$SCRIPT_DIR/.last-branch"
- # Archive previous run if branch changed
- if [ -f "$PRD_FILE" ] && [ -f "$LAST_BRANCH_FILE" ]; then
- CURRENT_BRANCH=$(jq -r '.branchName // empty' "$PRD_FILE" 2>/dev/null || echo "")
- LAST_BRANCH=$(cat "$LAST_BRANCH_FILE" 2>/dev/null || echo "")
- if [ -n "$CURRENT_BRANCH" ] && [ -n "$LAST_BRANCH" ] && [ "$CURRENT_BRANCH" != "$LAST_BRANCH" ]; then
- # Archive the previous run
- DATE=$(date +%Y-%m-%d)
- # Strip "ralph/" prefix from branch name for folder
- FOLDER_NAME=$(echo "$LAST_BRANCH" | sed 's|^ralph/||')
- ARCHIVE_FOLDER="$ARCHIVE_DIR/$DATE-$FOLDER_NAME"
- echo "Archiving previous run: $LAST_BRANCH"
- mkdir -p "$ARCHIVE_FOLDER"
- [ -f "$PRD_FILE" ] && cp "$PRD_FILE" "$ARCHIVE_FOLDER/"
- [ -f "$PROGRESS_FILE" ] && cp "$PROGRESS_FILE" "$ARCHIVE_FOLDER/"
- echo " Archived to: $ARCHIVE_FOLDER"
- # Reset progress file for new run
- echo "# Ralph Progress Log" > "$PROGRESS_FILE"
- echo "Started: $(date)" >> "$PROGRESS_FILE"
- echo "---" >> "$PROGRESS_FILE"
- fi
- fi
- # Track current branch
- if [ -f "$PRD_FILE" ]; then
- CURRENT_BRANCH=$(jq -r '.branchName // empty' "$PRD_FILE" 2>/dev/null || echo "")
- if [ -n "$CURRENT_BRANCH" ]; then
- echo "$CURRENT_BRANCH" > "$LAST_BRANCH_FILE"
- fi
- fi
- # Initialize progress file if it doesn't exist
- if [ ! -f "$PROGRESS_FILE" ]; then
- echo "# Ralph Progress Log" > "$PROGRESS_FILE"
- echo "Started: $(date)" >> "$PROGRESS_FILE"
- echo "---" >> "$PROGRESS_FILE"
- fi
- echo "Starting Ralph - Tool: $TOOL - Max iterations: $MAX_ITERATIONS"
- for i in $(seq 1 $MAX_ITERATIONS); do
- echo ""
- echo "==============================================================="
- echo " Ralph Iteration $i of $MAX_ITERATIONS ($TOOL)"
- echo "==============================================================="
- # Run the selected tool with the ralph prompt
- if [[ "$TOOL" == "amp" ]]; then
- OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" | amp --dangerously-allow-all 2>&1 | tee /dev/stderr) || true
- else
- # Claude Code: use --dangerously-skip-permissions for autonomous operation, --print for output
- Note: Starts a coding agent with its permission prompts off
- Line 94 on GitHub
- OUTPUT=$(claude --dangerously-skip-permissions --print < "$SCRIPT_DIR/CLAUDE.md" 2>&1 | tee /dev/stderr) || true
- Note: Starts a coding agent with its permission prompts off
- Line 95 on GitHub
- fi
- # Check for completion signal
- if echo "$OUTPUT" | grep -q "<promise>COMPLETE</promise>"; then
- echo ""
- echo "Ralph completed all tasks!"
- echo "Completed at iteration $i of $MAX_ITERATIONS"
- exit 0
- fi
- echo "Iteration $i complete. Continuing..."
- sleep 2
- done
- echo ""
- echo "Ralph reached max iterations ($MAX_ITERATIONS) without completing all tasks."
- echo "Check $PROGRESS_FILE for status."
- exit 1
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.