Skip to content
Back to search

ralph-marketplace

MarketplaceWorks with Claude CodeGitHub

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/snarktank-ralph/badge.svg)](/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)

  1. {
  2. "name": "ralph-marketplace",
  3. "owner": {
  4. "name": "snarktank"
  5. },
  6. "metadata": {
  7. "description": "Skills for the Ralph autonomous agent system - Generate PRDs and convert them to prd.json format for autonomous execution",
  8. "version": "1.0.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "ralph-skills",
  13. "source": "./",
  14. "description": "PRD generation and conversion skills for the Ralph autonomous agent loop",
  15. "version": "1.0.0",
  16. "keywords": ["ralph", "prd", "automation", "agent", "planning"],
  17. "category": "productivity",
  18. "skills": "./skills/"
  19. }
  20. ]
  21. }
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)

  1. # Ralph
  2. ![Ralph](ralph.webp)
  3. 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`.
  4. Based on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/).
  5. [Read my in-depth article on how I use Ralph](https://x.com/ryancarson/status/2008548371712135632)
  6. ## Prerequisites
  7. - One of the following AI coding tools installed and authenticated:
  8. - [Amp CLI](https://ampcode.com) (default)
  9. - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`npm install -g @anthropic-ai/claude-code`)
  10. - `jq` installed (`brew install jq` on macOS)
  11. - A git repository for your project
  12. ## Setup
  13. ### Option 1: Copy to your project
  14. Copy the ralph files into your project:
  15. ```bash
  16. # From your project root
  17. mkdir -p scripts/ralph
  18. cp /path/to/ralph/ralph.sh scripts/ralph/
  19. # Copy the prompt template for your AI tool of choice:
  20. cp /path/to/ralph/prompt.md scripts/ralph/prompt.md # For Amp
  21. # OR
  22. cp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md # For Claude Code
  23. chmod +x scripts/ralph/ralph.sh
  24. ```
  25. ### Option 2: Install skills globally (Amp)
  26. Copy the skills to your Amp or Claude config for use across all projects:
  27. For AMP
  28. ```bash
  29. cp -r skills/prd ~/.config/amp/skills/
  30. cp -r skills/ralph ~/.config/amp/skills/
  31. ```
  32. For Claude Code (manual)
  33. ```bash
  34. cp -r skills/prd ~/.claude/skills/
  35. cp -r skills/ralph ~/.claude/skills/
  36. ```
  37. ### Option 3: Use as Claude Code Marketplace
  38. Add the Ralph marketplace to Claude Code:
  39. ```bash
  40. /plugin marketplace add snarktank/ralph
  41. ```
  42. Then install the skills:
  43. ```bash
  44. /plugin install ralph-skills@ralph-marketplace
  45. ```
  46. Available skills after installation:
  47. - `/prd` - Generate Product Requirements Documents
  48. - `/ralph` - Convert PRDs to prd.json format
  49. Skills are automatically invoked when you ask Claude to:
  50. - "create a prd", "write prd for", "plan this feature"
  51. - "convert this prd", "turn into ralph format", "create prd.json"
  52. ### Configure Amp auto-handoff (recommended)
  53. Add to `~/.config/amp/settings.json`:
  54. ```json
  55. {
  56. "amp.experimental.autoHandoff": { "context": 90 }
  57. }
  58. ```
  59. This enables automatic handoff when context fills up, allowing Ralph to handle large stories that exceed a single context window.
  60. ## Workflow
  61. ### 1. Create a PRD
  62. Use the PRD skill to generate a detailed requirements document:
  63. ```
  64. Load the prd skill and create a PRD for [your feature description]
  65. ```
  66. Answer the clarifying questions. The skill saves output to `tasks/prd-[feature-name].md`.
  67. ### 2. Convert PRD to Ralph format
  68. Use the Ralph skill to convert the markdown PRD to JSON:
  69. ```
  70. Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json
  71. ```
  72. This creates `prd.json` with user stories structured for autonomous execution.
  73. ### 3. Run Ralph
  74. ```bash
  75. # Using Amp (default)
  76. ./scripts/ralph/ralph.sh [max_iterations]
  77. # Using Claude Code
  78. ./scripts/ralph/ralph.sh --tool claude [max_iterations]
  79. ```
  80. Default is 10 iterations. Use `--tool amp` or `--tool claude` to select your AI coding tool.
  81. Ralph will:
  82. 1. Create a feature branch (from PRD `branchName`)
  83. 2. Pick the highest priority story where `passes: false`
  84. 3. Implement that single story
  85. 4. Run quality checks (typecheck, tests)
  86. 5. Commit if checks pass
  87. 6. Update `prd.json` to mark story as `passes: true`
  88. 7. Append learnings to `progress.txt`
  89. 8. Repeat until all stories pass or max iterations reached
  90. ## Key Files
  91. | File | Purpose |
  92. |------|---------|
  93. | `ralph.sh` | The bash loop that spawns fresh AI instances (supports `--tool amp` or `--tool claude`) |
  94. | `prompt.md` | Prompt template for Amp |
  95. | `CLAUDE.md` | Prompt template for Claude Code |
  96. | `prd.json` | User stories with `passes` status (the task list) |
  97. | `prd.json.example` | Example PRD format for reference |
  98. | `progress.txt` | Append-only learnings for future iterations |
  99. | `skills/prd/` | Skill for generating PRDs (works with Amp and Claude Code) |
  100. | `skills/ralph/` | Skill for converting PRDs to JSON (works with Amp and Claude Code) |
  101. | `.claude-plugin/` | Plugin manifest for Claude Code marketplace discovery |
  102. | `flowchart/` | Interactive visualization of how Ralph works |
  103. ## Flowchart
  104. [![Ralph Flowchart](ralph-flowchart.png)](https://snarktank.github.io/ralph/)
  105. **[View Interactive Flowchart](https://snarktank.github.io/ralph/)** - Click through to see each step with animations.
  106. The `flowchart/` directory contains the source code. To run locally:
  107. ```bash
  108. cd flowchart
  109. npm install
  110. npm run dev
  111. ```
  112. ## Critical Concepts
  113. ### Each Iteration = Fresh Context
  114. Each iteration spawns a **new AI instance** (Amp or Claude Code) with clean context. The only memory between iterations is:
  115. - Git history (commits from previous iterations)
  116. - `progress.txt` (learnings and context)
  117. - `prd.json` (which stories are done)
  118. ### Small Tasks
  119. 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.
  120. Right-sized stories:
  121. - Add a database column and migration
  122. - Add a UI component to an existing page
  123. - Update a server action with new logic
  124. - Add a filter dropdown to a list
  125. Too big (split these):
  126. - "Build the entire dashboard"
  127. - "Add authentication"
  128. - "Refactor the API"
  129. ### AGENTS.md Updates Are Critical
  130. 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.
  131. Examples of what to add to AGENTS.md:
  132. - Patterns discovered ("this codebase uses X for Y")
  133. - Gotchas ("do not forget to update Z when changing W")
  134. - Useful context ("the settings panel is in component X")
  135. ### Feedback Loops
  136. Ralph only works if there are feedback loops:
  137. - Typecheck catches type errors
  138. - Tests verify behavior
  139. - CI must stay green (broken code compounds across iterations)
  140. ### Browser Verification for UI Stories
  141. 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.
  142. ### Stop Condition
  143. When all stories have `passes: true`, Ralph outputs `<promise>COMPLETE</promise>` and the loop exits.
  144. ## Debugging
  145. Check current state:
  146. ```bash
  147. # See which stories are done
  148. cat prd.json | jq '.userStories[] | {id, title, passes}'
  149. # See learnings from previous iterations
  150. cat progress.txt
  151. # Check git history
  152. git log --oneline -10
  153. ```
  154. ## Customizing the Prompt
  155. After copying `prompt.md` (for Amp) or `CLAUDE.md` (for Claude Code) to your project, customize it for your project:
  156. - Add project-specific quality check commands
  157. - Include codebase conventions
  158. - Add common gotchas for your stack
  159. ## Archiving
  160. Ralph automatically archives previous runs when you start a new feature (different `branchName`). Archives are saved to `archive/YYYY-MM-DD-feature-name/`.
  161. ## References
  162. - [Geoffrey Huntley's Ralph article](https://ghuntley.com/ralph/)
  163. - [Amp documentation](https://ampcode.com/manual)
  164. - [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code)
ralph.sh · Bundled script · 113 lines · 2 findings marked
  1. #!/bin/bash
  2. # Ralph Wiggum - Long-running AI agent loop
  3. # Usage: ./ralph.sh [--tool amp|claude] [max_iterations]
  4. set -e
  5. # Parse arguments
  6. TOOL="amp" # Default to amp for backwards compatibility
  7. MAX_ITERATIONS=10
  8. while [[ $# -gt 0 ]]; do
  9. case $1 in
  10. --tool)
  11. TOOL="$2"
  12. shift 2
  13. ;;
  14. --tool=*)
  15. TOOL="${1#*=}"
  16. shift
  17. ;;
  18. *)
  19. # Assume it's max_iterations if it's a number
  20. if [[ "$1" =~ ^[0-9]+$ ]]; then
  21. MAX_ITERATIONS="$1"
  22. fi
  23. shift
  24. ;;
  25. esac
  26. done
  27. # Validate tool choice
  28. if [[ "$TOOL" != "amp" && "$TOOL" != "claude" ]]; then
  29. echo "Error: Invalid tool '$TOOL'. Must be 'amp' or 'claude'."
  30. exit 1
  31. fi
  32. SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
  33. PRD_FILE="$SCRIPT_DIR/prd.json"
  34. PROGRESS_FILE="$SCRIPT_DIR/progress.txt"
  35. ARCHIVE_DIR="$SCRIPT_DIR/archive"
  36. LAST_BRANCH_FILE="$SCRIPT_DIR/.last-branch"
  37. # Archive previous run if branch changed
  38. if [ -f "$PRD_FILE" ] && [ -f "$LAST_BRANCH_FILE" ]; then
  39. CURRENT_BRANCH=$(jq -r '.branchName // empty' "$PRD_FILE" 2>/dev/null || echo "")
  40. LAST_BRANCH=$(cat "$LAST_BRANCH_FILE" 2>/dev/null || echo "")
  41. if [ -n "$CURRENT_BRANCH" ] && [ -n "$LAST_BRANCH" ] && [ "$CURRENT_BRANCH" != "$LAST_BRANCH" ]; then
  42. # Archive the previous run
  43. DATE=$(date +%Y-%m-%d)
  44. # Strip "ralph/" prefix from branch name for folder
  45. FOLDER_NAME=$(echo "$LAST_BRANCH" | sed 's|^ralph/||')
  46. ARCHIVE_FOLDER="$ARCHIVE_DIR/$DATE-$FOLDER_NAME"
  47. echo "Archiving previous run: $LAST_BRANCH"
  48. mkdir -p "$ARCHIVE_FOLDER"
  49. [ -f "$PRD_FILE" ] && cp "$PRD_FILE" "$ARCHIVE_FOLDER/"
  50. [ -f "$PROGRESS_FILE" ] && cp "$PROGRESS_FILE" "$ARCHIVE_FOLDER/"
  51. echo " Archived to: $ARCHIVE_FOLDER"
  52. # Reset progress file for new run
  53. echo "# Ralph Progress Log" > "$PROGRESS_FILE"
  54. echo "Started: $(date)" >> "$PROGRESS_FILE"
  55. echo "---" >> "$PROGRESS_FILE"
  56. fi
  57. fi
  58. # Track current branch
  59. if [ -f "$PRD_FILE" ]; then
  60. CURRENT_BRANCH=$(jq -r '.branchName // empty' "$PRD_FILE" 2>/dev/null || echo "")
  61. if [ -n "$CURRENT_BRANCH" ]; then
  62. echo "$CURRENT_BRANCH" > "$LAST_BRANCH_FILE"
  63. fi
  64. fi
  65. # Initialize progress file if it doesn't exist
  66. if [ ! -f "$PROGRESS_FILE" ]; then
  67. echo "# Ralph Progress Log" > "$PROGRESS_FILE"
  68. echo "Started: $(date)" >> "$PROGRESS_FILE"
  69. echo "---" >> "$PROGRESS_FILE"
  70. fi
  71. echo "Starting Ralph - Tool: $TOOL - Max iterations: $MAX_ITERATIONS"
  72. for i in $(seq 1 $MAX_ITERATIONS); do
  73. echo ""
  74. echo "==============================================================="
  75. echo " Ralph Iteration $i of $MAX_ITERATIONS ($TOOL)"
  76. echo "==============================================================="
  77. # Run the selected tool with the ralph prompt
  78. if [[ "$TOOL" == "amp" ]]; then
  79. OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" | amp --dangerously-allow-all 2>&1 | tee /dev/stderr) || true
  80. else
  81. # Claude Code: use --dangerously-skip-permissions for autonomous operation, --print for output
  82. OUTPUT=$(claude --dangerously-skip-permissions --print < "$SCRIPT_DIR/CLAUDE.md" 2>&1 | tee /dev/stderr) || true
  83. fi
  84. # Check for completion signal
  85. if echo "$OUTPUT" | grep -q "<promise>COMPLETE</promise>"; then
  86. echo ""
  87. echo "Ralph completed all tasks!"
  88. echo "Completed at iteration $i of $MAX_ITERATIONS"
  89. exit 0
  90. fi
  91. echo "Iteration $i complete. Continuing..."
  92. sleep 2
  93. done
  94. echo ""
  95. echo "Ralph reached max iterations ($MAX_ITERATIONS) without completing all tasks."
  96. echo "Check $PROGRESS_FILE for status."
  97. exit 1

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.