Ralph
A bash loop that restarts Claude Code or Amp with a clean context until every PRD story passes its checks, plus two skills for writing the PRD
High risk
We rate an entry high when the tool writes to external systems, handles money, production databases or secrets, or runs arbitrary commands. The CLI installs it only with your consent.
Why this level
- Runs Claude Code with --dangerously-skip-permissions and Amp with --dangerously-allow-all, so the agent executes any command without confirmation
- Creates branches and commits in the project repository on its own
- Runs unattended for up to 10 iterations by default, and each one spends model requests
Install
Manual install
/plugin marketplace add snarktank/ralph
/plugin install ralph-skills@ralph-marketplaceInstalls the /prd and /ralph skills. The plugin does not install ralph.sh, copy it into the project with the next method.
Security check
How we reviewHigh riskWe rate an entry high when the tool writes to external systems, handles money, production databases or secrets, or runs arbitrary commands. The CLI installs it only with your consent.
- Runs Claude Code with --dangerously-skip-permissions and Amp with --dangerously-allow-all, so the agent executes any command without confirmation
- Creates branches and commits in the project repository on its own
- Runs unattended for up to 10 iterations by default, and each one spends model requests
This is third-party code. Review the repository files before installing.
What it does
Ralph is a ralph.sh script that runs Claude Code or Amp in a loop, spawning a fresh instance with a clean context each time. In one iteration the agent picks the highest-priority unfinished story from prd.json, implements it, runs the typecheck and tests, and on success commits and marks the story as done. Memory between iterations lives in git history, a progress.txt log with learnings from earlier passes, and prd.json itself. The loop stops when every story passes or the iteration limit runs out, 10 by default. Two skills from the plugin prepare the input: prd asks clarifying questions and writes a Markdown PRD, ralph converts it to prd.json.
Who it is for. For Claude Code and Amp users ready to hand a whole feature to the agent once it is split into small stories with checkable criteria.
Good fit when
- The feature splits into small stories, each fitting into one context window
- The project has a typecheck, tests and CI that tell the agent a story is done
- A long task does not fit into a single agent session and the context overflows
- You want to write a PRD through clarifying questions first and then execute it unattended
Not a fit when
- The task cannot be broken down: a whole dashboard or the entire auth system will not fit into one iteration
- The project has no tests or typecheck, so errors pile up from one iteration to the next
- The agent must not run commands or commit without your confirmation
Example request
Load the prd skill and create a PRD for filtering tasks by priorityLimitations
Requires Amp CLI or Claude Code installed and signed in, the jq utility and a git repository for the project. The script supports two engines: Amp by default and Claude Code with the --tool claude flag. The Claude Code plugin installs only the prd and ralph skills, so ralph.sh and the prompt template are copied into the project by hand. The loop runs locally, but Claude Code and Amp call their model APIs, which from Russia usually requires a VPN.
How to disable. Stop the loop with Ctrl+C and delete the scripts/ralph folder from the project. Remove the plugin with /plugin uninstall ralph-skills@ralph-marketplace, and delete manually copied skills from ~/.claude/skills or ~/.config/amp/skills.
FAQ
How is Ralph different from one long agent session?
Each iteration starts with a clean context and takes a single story. Knowledge moves between iterations through commits, progress.txt and prd.json, so the model context does not overflow on a large task.
What does the marketplace plugin install?
Two Claude Code skills. The /prd skill asks 3–5 clarifying questions and saves the PRD to tasks/prd-[feature-name].md, and /ralph converts that document into prd.json. The plugin does not install the loop script, you copy it into the project.
How safe is it to run the loop?
The script runs Claude Code with --dangerously-skip-permissions and Amp with --dangerously-allow-all, so the agent runs commands and commits without confirmation. Run it in a copy of the repository or a container and start with a small limit, for example ./scripts/ralph/ralph.sh --tool claude 3.
Related
WorkflowsA skills library that gives coding agents a development process: brainstorming, planning, TDD, subagents and code review
Skills for real engineers by Matt Pocock
Skills For Real Engineers
Small composable skills for engineering with agents: plan grilling, TDD, bug diagnosis, code review and architecture
GitHub toolkit for spec-driven development: the specify CLI adds agent commands and skills to a project, from principles to implementation
Reference MCP servers
Model Context Protocol servers
Official reference MCP servers: Filesystem, Fetch, Git, Memory, Sequential Thinking, Time and Everything
README in short
The README presents Ralph as an implementation of Geoffrey Huntley's pattern and gives three install options: copying files into the project, installing the skills manually for Amp and Claude Code, and the Claude Code plugin marketplace. The workflow has three steps: a PRD via the prd skill, conversion to prd.json with the ralph skill, and running ralph.sh. Separate sections explain why stories must be small, why the agent appends learnings to AGENTS.md and why the loop accumulates errors without tests and a typecheck. For UI stories the author recommends adding a browser check with the dev-browser skill to the acceptance criteria. The README ends with debugging commands based on jq and git log.
README badge
Are you the author? Show in your README that the project is reviewed in the SkillFoxx catalog. The badge updates itself.
[](https://skillfoxx.ru/workflows/ralph?utm_source=github&utm_medium=badge&utm_campaign=readme)