ralph-marketplace

Ralph

Ralph is an autonomous AI agent loop that runs AI coding tools (Amp, Claude Code, or Codex CLI) repeatedly until every planned story has been turned into a merged PR. Each iteration is a fresh instance with clean context. Static task definition lives in prd.json; runtime lifecycle is tracked in a local state file under .git.

Based on Geoffrey Huntley's Ralph pattern.

Read my in-depth article on how I use Ralph

Prerequisites

• One of the following AI coding tools installed and authenticated:
  • Amp CLI (default)
  • Claude Code (npm install -g @anthropic-ai/claude-code)
  • Codex CLI (npm install -g @openai/codex)
• 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:

# 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
# OR
cp /path/to/ralph/CODEX.md scripts/ralph/CODEX.md      # For Codex CLI

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.

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.

2.5. Add the loop contract

You can define a lightweight merge gate:

{
  "loopConfig": {
    "fastCiCommand": "./scripts/ci_fast.sh",
    "mergeMethod": "merge"
  }
}

If loopConfig.fastCiCommand is present, Ralph uses it as the required validation gate for story branches. This should be the fast CI path, not a full release-grade CI run.

If loopConfig.fastCiCommand is omitted, Ralph falls back to the repository's default merge gate and tells the agent to run the normal CI, test, or typecheck command set for that codebase.

3. Run Ralph

# Using Amp (default)
./scripts/ralph/ralph.sh [max_iterations]

# Using Claude Code
./scripts/ralph/ralph.sh --tool claude [max_iterations]

# Using Codex CLI
./scripts/ralph/ralph.sh --tool codex [max_iterations]

Default is 10 iterations. Use --tool amp, --tool claude, or --tool codex to select your AI coding tool.

Ralph will:

1. Initialize or update a local runtime state file under .git/ralph-state.json
2. Pick the highest-priority story whose runtime state is not merged
3. Implement or resume that story on its own branch
4. Run the configured fast CI command, or fall back to the repository's default merge gate
5. Push the branch and open or update a PR to main
6. Mark the story ready_to_merge in local state when the branch tip is validated
7. Auto-merge the PR when it is mergeable
8. Sync merged PRs back into local state
9. Append learnings to progress.txt
10. Repeat until all stories are merged or max iterations reached

Ralph Light

ralph-lite.sh is the stripped-down Codex-only loop for a plain task-list or PR-plan document. It does not require prd.json, story state machines, or per-story bookkeeping.