claude-ralph

claude-ralph is an autonomous coding agent loop designed to transform Product Requirements Documents (PRDs) into fully implemented feature branches. By porting the proven Ralph pattern to the Claude Code CLI, this tool enables developers to offload repetitive implementation tasks to an AI that works iteratively. The agent processes a JSON-based PRD, selects high-priority user stories, and spawns clean, fresh Claude Code instances to handle the implementation, testing, and verification for each task individually. It maintains context and state across iterations using git, progress logs, and a structured task file, ensuring that the development process remains organized, high-quality, and reliable. Ideal for building complex features, the system includes built-in quality gates such as linting, typechecking, and automated testing. It also supports UI verification via Playwright for frontend stories. Users can define tasks in markdown, convert them to JSON, and let the autonomous loop handle everything from branch creation to codebase updates. This tool is perfect for solo developers or teams looking to accelerate their shipping velocity by leveraging their existing Claude Max subscriptions for deep, end-to-end autonomous coding cycles.

• Full autonomous loop execution: Automatically cycles through tasks in your prd.json until all stories are complete.

• Claude Code CLI integration: Utilizes your active Claude Pro or Max subscription via the official Claude Code interface.

• Iterative implementation: Breaks large features into small, atomic user stories that are easier for AI to manage and verify.

• Quality assurance: Enforces quality gates including typechecking, linting, and unit tests before every commit.

• UI Verification support: Includes specific handling for browser-based testing using Playwright.

• State persistence: Uses progress.txt and git history to track learnings, patterns, and codebase knowledge across sessions.

• Installation: Clone the repository into your scripts/ directory and follow the setup instructions for global or project-specific skill usage.

• Usage: Start by using the PRD skill to generate requirements, then convert them to prd.json for the autonomous runner.

• Prerequisites: Requires Claude Code CLI, jq, git, and optional Playwright for frontend testing.

• Workflow: Follow the iterative process of generating the PRD, refining user stories, and launching the autonomous ralph.sh loop.

• Best practices: Ensure stories are right-sized for a single coding session and include clear, binary acceptance criteria for best results.