Ralph: Autonomous AI Loop to Implement PRD Stories via Git

Ralph is an autonomous loop that spawns fresh AI instances to implement PRD user stories until tests and typechecks pass. State is preserved through git history, prd.json, and progress.txt, and it supports Amp CLI or Claude Code.

•
Tool
Ralph: Autonomous AI Loop to Implement PRD Stories via Git

TL;DR

  • Each iteration is a fresh AI instance; persistent state stored in git history, progress.txt, and prd.json.
  • Supported tools: Amp CLI (default) — https://ampcode.com, Claude Code — https://docs.anthropic.com/en/docs/claude-code; requires jq and a git repo; skills can be installed into Amp/Claude skill dirs; main runner scripts/ralph/ralph.sh.
  • PRD -> workflow: generate PRD (skills/prd to tasks/prd-[feature].md), convert to prd.json via ralph skill, run loop ./scripts/ralph/ralph.sh [max_iterations] or --tool claude [max_iterations].
  • Single-story iteration: create feature branch, pick highest-priority story with passes: false, implement, run typechecks and tests, commit if checks pass, mark passes: true, append learnings to progress.txt.
  • Reliability rules: right-sized stories to fit one context window, robust typechecks/tests/CI to prevent compounding failures, AGENTS.md updated each iteration, frontend acceptance should include browser verification via dev-browser skill.
  • Visualization & debugging: interactive flowchart — https://snarktank.github.io/ralph/, inspect prd.json with jq, view progress.txt and recent commits, runs archived under archive/YYYY-MM-DD-feature-name/.

Ralph repository describes an autonomous AI agent loop that repeatedly drives AI coding tools to implement user stories from a PRD until all quality checks pass. The loop spawns a fresh AI instance each iteration and preserves state through git history, progress.txt, and prd.json, enabling incremental, auditable progress across runs.

Prerequisites and setup

Ralph relies on one of two supported AI coding tools:

Additional tooling includes jq and a git repository for the project. Files and skills can be copied directly into a project or installed globally into Amp/Claude skill directories. Example installation snippets live in the repo; the main runner is a shell script at scripts/ralph/ralph.sh.

Workflow

The intended workflow is structured and iterative:

  1. Generate a PRD using the prd skill; the output is saved to tasks/prd-[feature-name].md.
  2. Convert the markdown PRD to a machine-actionable prd.json via the ralph skill.
  3. Run the loop with the shell script:
    • Using Amp (default): ./scripts/ralph/ralph.sh [max_iterations]
    • Using Claude Code: ./scripts/ralph/ralph.sh --tool claude [max_iterations]

Each iteration follows a single-story lifecycle:

  • Create a feature branch (from PRD branchName)
  • Pick the highest-priority story with passes: false
  • Implement that story
  • Run typechecks and tests
  • Commit if checks pass
  • Mark the story passes: true in prd.json
  • Append learnings to progress.txt
  • Repeat until all stories pass or the max iteration count is reached

Key files and components

  • ralph.sh — the bash loop that spawns fresh AI instances (supports --tool amp or --tool claude)
  • prompt.md, CLAUDE.md — prompt templates for Amp and Claude Code
  • prd.json — structured user stories with passes status
  • progress.txt — append-only learnings for future iterations
  • skills/prd/, skills/ralph/ — PRD generation and conversion skills
  • flowchart/ — interactive visualization source

Critical concepts for reliable runs

  • Each iteration is a fresh AI instance. The only persistent memory is commits, progress.txt, and prd.json.
  • Right-sized stories. Tasks must be small enough to fit a single context window (e.g., add a DB column, update a UI component). Large tasks should be split.
  • Feedback loops matter. Reliable typechecks, tests, and CI are required; broken CI compounds across iterations.
  • AGENTS.md updates. After each iteration, the loop updates AGENTS.md so future AI instances (and humans) inherit discovered patterns and gotchas.
  • Browser verification for UI stories. Frontend acceptance criteria should include browser verification via the dev-browser skill.

Visualization, debugging, and customization

An interactive flowchart lives at https://snarktank.github.io/ralph/. The repo includes commands for inspecting state (e.g., using jq on prd.json, viewing progress.txt, and checking recent git commits). Prompts can be customized to include project-specific quality checks, codebase conventions, and common pitfalls. Ralph also archives previous runs under archive/YYYY-MM-DD-feature-name/.

References

Ralph builds on the Ralph pattern from Geoffrey Huntley: https://ghuntley.com/ralph/. Additional links in the repo point to Amp documentation (https://ampcode.com/manual) and Claude Code docs (https://docs.anthropic.com/en/docs/claude-code).

Original source: https://github.com/snarktank/ralph

Continue the conversation on Slack

Did this article spark your interest? Join our community of experts and enthusiasts to dive deeper, ask questions, and share your ideas.

Join our community

Related Articles

tool cover

ChunkHound: Fast Local-First Code Semantic Search and Code Intelligence

ChunkHound indexes repositories locally using a research-backed cAST algorithm to create semantic chunks, offering semantic and regex search plus multi-hop code discovery. Optional LLM integrations and MCP support enable deep, private code research for large monorepos.

1 shared tag
tool cover

agent-browser: Fast Rust CLI and Playwright Daemon for AI Agents

agent-browser pairs a fast Rust CLI with a Node.js Playwright daemon to provide deterministic, AI-friendly browser automation via snapshots and refs. It offers semantic locators, JSON output for LLMs, session isolation, network mocking, and headed/CDP modes.

1 shared tag
tool cover

ClawdHub Launches AgentSkills Registry for Versioned, Searchable AI Tools

Peter Steinberger's ClawdHub is an open-source registry for AgentSkills bundles, offering versioned package installs and rollback-ready updates. It features vector-based semantic search, npx install commands, and a web UI for browsing, uploading, and discovering reusable agent capabilities.

1 shared tag