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, and Docker projects.

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

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
npx agentic-loop run --fast  # Skip code review (~2x faster)

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                                │
│  4. Run verification (lint, tests, browser, code review)    │
│  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
• Cheatsheet - All commands at a glance
• Hooks Reference - Pre-commit and Claude Code hooks
• Troubleshooting - Common issues and fixes
• Contributing - How to contribute

MIT License - AllThrive AI