snarktank/ralph

★ 19,224TypeScriptAudience · developerComplexity · 3/5MaintainedLicenseSetup · moderate

Mindmap

mindmap
  root((repo))
    What it does
      Runs AI coding tools
      Completes task batches
      Tracks progress
      Commits to Git
    How it works
      Reads PRD JSON file
      Launches fresh AI session
      Runs quality checks
      Marks tasks done
    Tech stack
      TypeScript
      Shell script
      Git
      jq
    Use cases
      Automate feature lists
      Batch coding tasks
      Autonomous backlog work
    Requirements
      Amp CLI or Claude Code
      Git repository
      Task list format

mindmap root((repo)) What it does Runs AI coding tools Completes task batches Tracks progress Commits to Git How it works Reads PRD JSON file Launches fresh AI session Runs quality checks Marks tasks done Tech stack TypeScript Shell script Git jq Use cases Automate feature lists Batch coding tasks Autonomous backlog work Requirements Amp CLI or Claude Code Git repository Task list format

Things people build with this

USE CASE 1

Automate implementation of a feature list by converting a PRD into tasks and letting Ralph work through them autonomously.

USE CASE 2

Complete a backlog of well-defined coding tasks without manually prompting an AI assistant for each one.

USE CASE 3

Build large features that span multiple AI context windows by using Git history and progress tracking to maintain state.

Tech stack

TypeScriptShell scriptGitjqAmp CLIClaude Code

Getting it running

Difficulty · moderate Time to first run · 30min

Requires Claude API key and Amp CLI installation; automation loop needs proper environment configuration.

Use freely for any purpose including commercial, as long as you keep the copyright notice.

In plain English

Ralph is an automation loop that runs AI coding tools, specifically Amp or Claude Code, repeatedly in a batch until an entire list of software tasks is finished. Instead of manually prompting an AI assistant one task at a time, you write a Product Requirements Document (a structured list of features and user stories), convert it into a JSON task file called prd.json, and then run Ralph. It picks the next unfinished story, launches a fresh AI coding session to implement it, runs quality checks (type checking and tests), commits the result to Git, marks the story as done, and then repeats, up to a configurable number of iterations. Each iteration starts with a clean context window (no memory of previous sessions), so Ralph keeps state using three simple files: the git commit history, a progress.txt file where each run appends learnings, and the prd.json file that tracks which stories pass. This design means even large features, spanning many context windows, can be completed autonomously. You would use Ralph if you want to automate a series of well-defined coding tasks end-to-end, stepping back while the AI works through a backlog. It requires either the Amp CLI or Claude Code installed, plus jq and a git repository. The project is written in TypeScript and shell script.

Copy-paste prompts

Prompt 1

How do I set up Ralph to automate a list of coding tasks from my PRD?

Prompt 2

Show me how to structure a prd.json file so Ralph can parse and execute my feature list.

Prompt 3

How does Ralph maintain state across multiple AI coding sessions when the context window resets?

Prompt 4

What quality checks does Ralph run after each task, and how do I customize them?

Prompt 5

Can I use Ralph with Claude Code instead of Amp, and what's the setup difference?

Open on GitHub → Explain another repo

Generated 2026-05-18 · Model: sonnet-4-6 · Verify against the repo before relying on details.