Ralph (Copilot CLI Fork)

Fork of snarktank/ralph — adds GitHub Copilot CLI as a supported AI coding tool alongside Amp and Claude Code.

Ralph is an autonomous AI agent loop that runs AI coding tools 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.

Read the in-depth article on how Ralph is used

What this fork adds

The upstream Ralph supports Amp and Claude Code. This fork extends it with GitHub Copilot CLI support (--tool copilot), allowing you to use Claude Opus 4.6 via Copilot as the underlying model for Ralph iterations.

Key changes from upstream:

• ralph.sh — added --tool copilot option that invokes copilot --allow-all --model claude-opus-4.6
• COPILOT.md — dedicated prompt template for GitHub Copilot CLI
• CLAUDE.md — original prompt template for Claude Code (kept from upstream)
• AGENTS.md — updated to reflect Copilot CLI support

Prerequisites

• One of the following AI coding tools installed and authenticated:
  • Amp CLI (default)
  • Claude Code (npm install -g @anthropic-ai/claude-code)
  • GitHub Copilot CLI (gh extension install github/gh-copilot)
• 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/COPILOT.md scripts/ralph/COPILOT.md    # For GitHub Copilot 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.

3. Run Ralph

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

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

# Using GitHub Copilot CLI (Claude Opus 4.6)
./scripts/ralph/ralph.sh --tool copilot [max_iterations]

Default is 10 iterations. Use --tool amp, --tool claude, or --tool copilot 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, --tool claude, or --tool copilot)
prompt.md	Prompt template for Amp
CLAUDE.md	Prompt template for Claude Code
COPILOT.md	Prompt template for GitHub Copilot CLI
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

View Interactive Flowchart - Click through to see each step with animations.

The flowchart/ directory contains the source code. To run locally:

cd flowchart
npm install
npm run dev

Critical Concepts

Each Iteration = Fresh Context

Each iteration spawns a new AI instance (Amp, Claude Code, or GitHub Copilot CLI) 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:

# 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), CLAUDE.md (for Claude Code), or COPILOT.md (for GitHub Copilot CLI) to your project, customize it for your project:

• Add project-specific quality check commands
• Include codebase conventions
• Add common gotchas for your stack

Syncing with Upstream

To pull in updates from the original Ralph project without losing fork changes:

git remote add upstream https://github.com/snarktank/ralph.git  # only needed once
git fetch upstream
git merge upstream/main

If there are merge conflicts (likely in ralph.sh or AGENTS.md), resolve them manually to keep the Copilot CLI additions. No fork changes are lost — Git will ask you to choose what to keep when both sides modified the same lines.

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

• Upstream Ralph (snarktank/ralph)
• Geoffrey Huntley's Ralph article
• Amp documentation
• Claude Code documentation
• GitHub Copilot CLI documentation