{"id":37170329,"url":"https://github.com/snarktank/ralph","last_synced_at":"2026-02-15T07:11:40.363Z","repository":{"id":333724876,"uuid":"1129759677","full_name":"snarktank/ralph","owner":"snarktank","description":"Ralph is an autonomous AI agent loop that runs repeatedly until all PRD items are complete. ","archived":false,"fork":false,"pushed_at":"2026-02-02T01:46:21.000Z","size":4705,"stargazers_count":9120,"open_issues_count":29,"forks_count":1076,"subscribers_count":70,"default_branch":"main","last_synced_at":"2026-02-02T11:33:39.987Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://x.com/ryancarson/status/2008548371712135632","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/snarktank.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-07T14:45:10.000Z","updated_at":"2026-02-02T10:59:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/snarktank/ralph","commit_stats":null,"previous_names":["snarktank/ralph"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/snarktank/ralph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snarktank%2Fralph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snarktank%2Fralph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snarktank%2Fralph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snarktank%2Fralph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/snarktank","download_url":"https://codeload.github.com/snarktank/ralph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/snarktank%2Fralph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29472879,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-15T06:58:05.414Z","status":"ssl_error","status_checked_at":"2026-02-15T06:58:05.085Z","response_time":118,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-14T20:00:22.942Z","updated_at":"2026-02-15T07:11:40.358Z","avatar_url":"https://github.com/snarktank.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","Implementations","🌟 Community Agent Harnesses","A01_文本生成_文本对话","🎭 Multi-Agent Orchestration","Repos","Task Runners","Development Workflows \u0026 Agents","🏆 القائمة الكاملة Top 200","Tools \u0026 Frameworks"],"sub_categories":["Coding \u0026 Development","大语言对话模型及数据","Standalone Implementations","Other IDEs"],"readme":"# Ralph\n\n![Ralph](ralph.webp)\n\nRalph is an autonomous AI agent loop that runs AI coding tools ([Amp](https://ampcode.com) or [Claude Code](https://docs.anthropic.com/en/docs/claude-code)) 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`.\n\nBased on [Geoffrey Huntley's Ralph pattern](https://ghuntley.com/ralph/).\n\n[Read my in-depth article on how I use Ralph](https://x.com/ryancarson/status/2008548371712135632)\n\n## Prerequisites\n\n- One of the following AI coding tools installed and authenticated:\n  - [Amp CLI](https://ampcode.com) (default)\n  - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) (`npm install -g @anthropic-ai/claude-code`)\n- `jq` installed (`brew install jq` on macOS)\n- A git repository for your project\n\n## Setup\n\n### Option 1: Copy to your project\n\nCopy the ralph files into your project:\n\n```bash\n# From your project root\nmkdir -p scripts/ralph\ncp /path/to/ralph/ralph.sh scripts/ralph/\n\n# Copy the prompt template for your AI tool of choice:\ncp /path/to/ralph/prompt.md scripts/ralph/prompt.md    # For Amp\n# OR\ncp /path/to/ralph/CLAUDE.md scripts/ralph/CLAUDE.md    # For Claude Code\n\nchmod +x scripts/ralph/ralph.sh\n```\n\n### Option 2: Install skills globally (Amp)\n\nCopy the skills to your Amp or Claude config for use across all projects:\n\nFor AMP\n```bash\ncp -r skills/prd ~/.config/amp/skills/\ncp -r skills/ralph ~/.config/amp/skills/\n```\n\nFor Claude Code (manual)\n```bash\ncp -r skills/prd ~/.claude/skills/\ncp -r skills/ralph ~/.claude/skills/\n```\n\n### Option 3: Use as Claude Code Marketplace\n\nAdd the Ralph marketplace to Claude Code:\n\n```bash\n/plugin marketplace add snarktank/ralph\n```\n\nThen install the skills:\n\n```bash\n/plugin install ralph-skills@ralph-marketplace\n```\n\nAvailable skills after installation:\n- `/prd` - Generate Product Requirements Documents\n- `/ralph` - Convert PRDs to prd.json format\n\nSkills are automatically invoked when you ask Claude to:\n- \"create a prd\", \"write prd for\", \"plan this feature\"\n- \"convert this prd\", \"turn into ralph format\", \"create prd.json\"\n\n### Configure Amp auto-handoff (recommended)\n\nAdd to `~/.config/amp/settings.json`:\n\n```json\n{\n  \"amp.experimental.autoHandoff\": { \"context\": 90 }\n}\n```\n\nThis enables automatic handoff when context fills up, allowing Ralph to handle large stories that exceed a single context window.\n\n## Workflow\n\n### 1. Create a PRD\n\nUse the PRD skill to generate a detailed requirements document:\n\n```\nLoad the prd skill and create a PRD for [your feature description]\n```\n\nAnswer the clarifying questions. The skill saves output to `tasks/prd-[feature-name].md`.\n\n### 2. Convert PRD to Ralph format\n\nUse the Ralph skill to convert the markdown PRD to JSON:\n\n```\nLoad the ralph skill and convert tasks/prd-[feature-name].md to prd.json\n```\n\nThis creates `prd.json` with user stories structured for autonomous execution.\n\n### 3. Run Ralph\n\n```bash\n# Using Amp (default)\n./scripts/ralph/ralph.sh [max_iterations]\n\n# Using Claude Code\n./scripts/ralph/ralph.sh --tool claude [max_iterations]\n```\n\nDefault is 10 iterations. Use `--tool amp` or `--tool claude` to select your AI coding tool.\n\nRalph will:\n1. Create a feature branch (from PRD `branchName`)\n2. Pick the highest priority story where `passes: false`\n3. Implement that single story\n4. Run quality checks (typecheck, tests)\n5. Commit if checks pass\n6. Update `prd.json` to mark story as `passes: true`\n7. Append learnings to `progress.txt`\n8. Repeat until all stories pass or max iterations reached\n\n## Key Files\n\n| File | Purpose |\n|------|---------|\n| `ralph.sh` | The bash loop that spawns fresh AI instances (supports `--tool amp` or `--tool claude`) |\n| `prompt.md` | Prompt template for Amp |\n| `CLAUDE.md` | Prompt template for Claude Code |\n| `prd.json` | User stories with `passes` status (the task list) |\n| `prd.json.example` | Example PRD format for reference |\n| `progress.txt` | Append-only learnings for future iterations |\n| `skills/prd/` | Skill for generating PRDs (works with Amp and Claude Code) |\n| `skills/ralph/` | Skill for converting PRDs to JSON (works with Amp and Claude Code) |\n| `.claude-plugin/` | Plugin manifest for Claude Code marketplace discovery |\n| `flowchart/` | Interactive visualization of how Ralph works |\n\n## Flowchart\n\n[![Ralph Flowchart](ralph-flowchart.png)](https://snarktank.github.io/ralph/)\n\n**[View Interactive Flowchart](https://snarktank.github.io/ralph/)** - Click through to see each step with animations.\n\nThe `flowchart/` directory contains the source code. To run locally:\n\n```bash\ncd flowchart\nnpm install\nnpm run dev\n```\n\n## Critical Concepts\n\n### Each Iteration = Fresh Context\n\nEach iteration spawns a **new AI instance** (Amp or Claude Code) with clean context. The only memory between iterations is:\n- Git history (commits from previous iterations)\n- `progress.txt` (learnings and context)\n- `prd.json` (which stories are done)\n\n### Small Tasks\n\nEach 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.\n\nRight-sized stories:\n- Add a database column and migration\n- Add a UI component to an existing page\n- Update a server action with new logic\n- Add a filter dropdown to a list\n\nToo big (split these):\n- \"Build the entire dashboard\"\n- \"Add authentication\"\n- \"Refactor the API\"\n\n### AGENTS.md Updates Are Critical\n\nAfter 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.\n\nExamples of what to add to AGENTS.md:\n- Patterns discovered (\"this codebase uses X for Y\")\n- Gotchas (\"do not forget to update Z when changing W\")\n- Useful context (\"the settings panel is in component X\")\n\n### Feedback Loops\n\nRalph only works if there are feedback loops:\n- Typecheck catches type errors\n- Tests verify behavior\n- CI must stay green (broken code compounds across iterations)\n\n### Browser Verification for UI Stories\n\nFrontend 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.\n\n### Stop Condition\n\nWhen all stories have `passes: true`, Ralph outputs `\u003cpromise\u003eCOMPLETE\u003c/promise\u003e` and the loop exits.\n\n## Debugging\n\nCheck current state:\n\n```bash\n# See which stories are done\ncat prd.json | jq '.userStories[] | {id, title, passes}'\n\n# See learnings from previous iterations\ncat progress.txt\n\n# Check git history\ngit log --oneline -10\n```\n\n## Customizing the Prompt\n\nAfter copying `prompt.md` (for Amp) or `CLAUDE.md` (for Claude Code) to your project, customize it for your project:\n- Add project-specific quality check commands\n- Include codebase conventions\n- Add common gotchas for your stack\n\n## Archiving\n\nRalph automatically archives previous runs when you start a new feature (different `branchName`). Archives are saved to `archive/YYYY-MM-DD-feature-name/`.\n\n## References\n\n- [Geoffrey Huntley's Ralph article](https://ghuntley.com/ralph/)\n- [Amp documentation](https://ampcode.com/manual)\n- [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnarktank%2Fralph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsnarktank%2Fralph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsnarktank%2Fralph/lists"}