Agentic Loop

Autonomous AI coding loop for Claude Code.

You describe what you want to build. Claude Code writes a PRD (Product Requirements Document) with small, testable stories. Ralph executes each story automatically - coding, testing, and committing in a loop until everything passes.

Optimized for: Python, TypeScript, React, Go/Hugo, FastMCP, and Docker projects.

Supported Project Types

Ralph auto-detects your project type and configures itself accordingly:

Type	Detection	Auto-Configured
FastMCP	`fastmcp` in pyproject.toml	Server module, MCP port, transport, subprojects
FastAPI	`fastapi` in pyproject.toml	uvicorn dev server, pytest, ruff
Django	`django` in pyproject.toml or manage.py	migrations, pytest, ruff
Python	pyproject.toml or requirements.txt	pytest, ruff, uv/poetry detection
Node.js	package.json	npm/yarn/pnpm, vitest/jest, eslint
React	`react` in package.json	Vite/Next.js, TypeScript, Tailwind
Go/Hugo	go.mod or hugo.toml	Hugo server, Go build
Rust	Cargo.toml	cargo build/test/clippy
Fullstack	frontend + backend directories	Monorepo support, separate configs

What It Does

Brainstorm ideas with /idea Describe a feature in plain English. Claude asks clarifying questions, explores your codebase, and generates a PRD with atomic stories that can be implemented one at a time.

Execute with Ralph Ralph reads the PRD and implements each story autonomously. It spawns Claude, runs verification (lint, tests, browser checks), and either commits on success or retries with error context on failure.

Customize your output

/my-dna - Add your voice and values so the code reflects your style
/styleguide - Generate a UI component reference for consistent design

Built-in guardrails

/vibe-check, /review - On-demand quality and security checks
Pre-commit hooks - Block secrets, hardcoded URLs, debug statements
Claude Code hooks - Real-time warnings while coding
GitHub Actions CI/CD - Fast PR checks + comprehensive nightly tests
Test file enforcement - Fails if new code lacks corresponding tests

Quick Start

Prerequisites: Node.js 18+, Claude Code CLI, jq (brew install jq)

npm install agentic-loop
npx agentic-loop setup

Terminal 1 - Claude Code:

claude --dangerously-skip-permissions
/tour                    # Guided walkthrough (recommended first time)
/idea 'your feature'     # Generate a PRD

Terminal 2 - Ralph Loop:

npx agentic-loop run         # Execute PRDs autonomously

Tip: Use two terminals. Plan with Claude in one, run Ralph in the other.

How Ralph Works

┌─────────────────────────────────────────────────────────────┐
│                        RALPH LOOP                           │
├─────────────────────────────────────────────────────────────┤
│  1. Read prd.json → find next story where passes=false      │
│  2. Build prompt (story + context + failures + signs)       │
│  3. Spawn Claude with prompt + MCP browser tools            │
│  4. Run verification (lint, tests, testSteps)               │
│  5. Pass? → commit, next story                              │
│     Fail? → save error, retry with failure context          │
│  6. Repeat until all stories pass                           │
└─────────────────────────────────────────────────────────────┘

What's a PRD? A JSON file (.ralph/prd.json) containing your feature broken into small stories. Each story has acceptance criteria, test steps, and a test URL. Ralph implements them one by one.

What are Signs? Patterns Ralph learns from failures. If Ralph keeps making the same mistake, add a sign: npx agentic-loop sign "Always use camelCase for API fields" backend. Future stories will see this guidance.

Docs

How Ralph Works - Architecture, config, verification pipeline
Technical Architecture - Deep dive for developers
Cheatsheet - All commands at a glance
Hooks Reference - Pre-commit and Claude Code hooks
Troubleshooting - Common issues and fixes
Contributing - How to contribute

Inspired by Ralph and Anthropic's guidance on long-running agents.

Built by @allierays | MIT License - AllThrive AI