Ralph

Ralph is an autonomous AI agent loop that runs AI coding tools (Amp, Claude Code, GitHub Copilot CLI, or ChatGPT Codex) in a planner-routed loop until a global final success criteria is met. Each planner pass chooses the next focused agent handoff (developer, uxui, documentation, WEB_BROWSER_SAFE, or WEB_BROWSER_BYPASS). Each phase is a fresh instance with clean context. Memory persists via git history, progress.txt, and the evolving prd.json.

Based on Geoffrey Huntley's Ralph pattern.

Read my in-depth article on how I use Ralph

• 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 (npm install -g @github/copilot)
  • ChatGPT Codex CLI (npm i -g @openai/codex)
• jq installed (brew install jq on macOS)
• A git repository for your project

Install Ralph globally from this repo:

git clone https://github.com/samchung95/ralph-cli.git
cd ralph-cli/cli
npm install
npm run build
npm install -g .

The ralph-cli package name on npm is currently a placeholder and does not expose the ralph command. Until this CLI is published, install from the local cli package.

Initialize Ralph in your project:

cd your-project
ralph init

This creates progress.txt. Ralph keeps role prompts (PLANNER.md, DEVELOPER.md, UXUI.md, DOCUMENTATION.md, WEB_BROWSER_SAFE.md, WEB_BROWSER_BYPASS.md, DOCTOR.md), PROGRESS_INSTRUCT.md, and prd.json.example bundled in the installed package instead of copying them into your project root.

Install the /ralph setup skill into your AI tool:

# Claude Code (default)
ralph install

# Amp
ralph install --tool amp

# GitHub Copilot CLI
ralph install --tool copilot

# ChatGPT Codex
ralph install --tool codex

ralph install replaces any existing /ralph skill folder for the selected tool before installing the bundled copy.

Codex can optionally run with full access. This setting is remembered:

ralph bypass status
ralph bypass on
ralph bypass off

When bypass is on, ralph run --tool codex uses Codex's --dangerously-bypass-approvals-and-sandbox mode. Leave bypass off for sandboxed --full-auto runs.

Copilot can optionally auto-approve prompts that still appear despite --allow-all:

ralph auto-approve status
ralph auto-approve on
ralph auto-approve off

When Copilot auto-approve is on, Ralph watches Copilot output for approval prompts and answers them automatically.

You can also copy the shell runner into a project:

# From your project root
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/
cp /path/to/ralph/cli/templates/PLANNER.md scripts/ralph/PLANNER.md
cp /path/to/ralph/cli/templates/DEVELOPER.md scripts/ralph/DEVELOPER.md
cp /path/to/ralph/cli/templates/UXUI.md scripts/ralph/UXUI.md
cp /path/to/ralph/cli/templates/DOCUMENTATION.md scripts/ralph/DOCUMENTATION.md
cp /path/to/ralph/cli/templates/WEB_BROWSER_SAFE.md scripts/ralph/WEB_BROWSER_SAFE.md
cp /path/to/ralph/cli/templates/WEB_BROWSER_BYPASS.md scripts/ralph/WEB_BROWSER_BYPASS.md
cp /path/to/ralph/cli/templates/PROGRESS_INSTRUCT.md scripts/ralph/PROGRESS_INSTRUCT.md
cp /path/to/ralph/cli/templates/prd.json.example scripts/ralph/prd.json.example

chmod +x scripts/ralph/ralph.sh

If you are not using ralph install, copy the setup skill manually:

For Amp:

cp -r skills/ralph ~/.config/amp/skills/

For Claude Code:

cp -r skills/ralph ~/.claude/skills/

For GitHub Copilot CLI:

cp -r skills/ralph ~/.copilot/skills/

For ChatGPT Codex:

cp -r skills/ralph ~/.agents/skills/

Add the Ralph marketplace to Claude Code:

/plugin marketplace add snarktank/ralph

Then install the skill:

/plugin install ralph-skills@ralph-marketplace

The skill is automatically invoked when you ask Claude to:

• "set up ralph", "start ralph", "plan this with ralph"
• "create prd.json", "prepare the initial ralph step"

Add to ~/.config/amp/settings.json:

{
  "amp.experimental.autoHandoff": { "context": 90 }
}

This enables automatic handoff when context fills up, allowing Ralph to handle large assignments that exceed a single context window.

Use the Ralph skill to create the initial evolving prd.json:

Load the ralph skill and set up Ralph for [your feature description]

Answer any clarifying questions. The skill expands your rough prompt into finalSuccessCriteria, planner context, and a compact progress.txt. Ralph starts with the planner, which writes planning.activeHandoff and chooses the first agent.

With the Node CLI:

# Claude Code, 10 cycles by default
ralph run

# Claude Code, 20 cycles
ralph run 20

# Amp
ralph run --tool amp

# GitHub Copilot CLI
ralph run --tool copilot

# GitHub Copilot CLI with auto-approval for this run only
ralph run --tool copilot --auto-approve

# ChatGPT Codex
ralph run --tool codex

# ChatGPT Codex with full access for this run only
ralph run --tool codex --bypass

# Fully autonomous Claude Code mode
ralph run --dangerously-skip-permissions 15

# Optional helpers
ralph validate
ralph reset
ralph fix

With the copied shell script:

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

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

# Using GitHub Copilot CLI
./scripts/ralph/ralph.sh --tool copilot [max_cycles]

# Using ChatGPT Codex
./scripts/ralph/ralph.sh --tool codex [max_cycles]

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

Ralph will:

1. Create a feature branch (from PRD branchName)
2. Run a planner phase from PLANNER.md
3. Let the planner check finalSuccessCriteria
4. If success criteria pass, output <promise>COMPLETE</promise>
5. Otherwise, write planning.activeHandoff with the selected agent, objective, scope, rules, comments, and handoff success criteria
6. Run the selected role prompt (DEVELOPER.md, UXUI.md, DOCUMENTATION.md, WEB_BROWSER_SAFE.md, or WEB_BROWSER_BYPASS.md) merged with PROGRESS_INSTRUCT.md
7. Let the selected agent complete or block the handoff and update progress.txt
8. Return to the planner and repeat

Ralph validates the prd.json structure before the run starts, at the start of every cycle, and after every planner or selected-agent phase. If an agent leaves the PRD in an invalid state, the run stops immediately instead of continuing with a broken planning chain.

Use these helper commands with the Node CLI:

ralph validate   # Validate prd.json structure and cycle consistency
ralph reset      # Archive current prd/progress and restore a fresh prd.json before authoring the next PRD

To update your global ralph command after changing this checkout, run:

cd /path/to/ralph-cli/cli
npm run build
npm install -g .

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

Each planner or selected-agent phase spawns a new AI instance (Amp, Claude Code, GitHub Copilot CLI, or ChatGPT Codex) with clean context. The only memory between phases is:

• Git history (commits from previous phases)
• progress.txt (learnings and context)
• prd.json (active handoff, PRD chain, and final success criteria)

Ralph no longer needs a fully preplanned backlog. The first prd.json contains a global finalSuccessCriteria and planner context expanded from the user's prompt. Each planner pass checks the work so far. If the final criteria are not met, it writes the next focused planning.activeHandoff and records the chain in prdChain.

Each handoff 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 handoffs:

• 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"

After each selected-agent phase, Ralph can update relevant agent instruction files with genuinely reusable learnings. This is key because AI coding tools automatically read these files, so future phases and future human developers benefit from discovered patterns, gotchas, and conventions.

Examples of what to add to agent instruction files:

• 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")

Ralph only works if there are feedback loops:

• Typecheck catches type errors
• Tests verify behavior
• CI must stay green (broken code compounds across iterations)

Frontend handoffs must include browser verification in planning.activeHandoff.successCriteria. Ralph will use available browser tooling to navigate to the page, interact with the UI, and confirm changes work.

When the planner verifies finalSuccessCriteria.passes: true, it outputs <promise>COMPLETE</promise> and the loop exits.

Check current state:

# See the active planner handoff
cat prd.json | jq '.planning.activeHandoff'

# See global completion status
cat prd.json | jq '.finalSuccessCriteria'

# See learnings from previous iterations
cat progress.txt

# Check git history
git log --oneline -10

If you're using the copied shell script with project-local role prompts, customize them for your project:

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

Ralph automatically archives previous runs when you start a new feature (different branchName). Archives are saved to archive/<timestamp>-feature-name/.

• Geoffrey Huntley's Ralph article
• Amp documentation
• Claude Code documentation
• GitHub Copilot CLI documentation
• ChatGPT Codex CLI documentation