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.
┌──────────────────────────────────────────────────────────────────────────────────┐
│ TERMINAL 1: Claude CLI │ TERMINAL 2: Execute │
├────────────────────────────────────────┼─────────────────────────────────────────┤
│ │ │
│ claude --dangerously-skip-permissions │ npx agentic-loop run │
│ │ │
│ PLAN FEATURES │ ┌─ prd-check (once) ───────────────┐ │
│ /idea 'your feature or bugfix' │ │ Validate all stories upfront │ │
│ → Claude asks questions │ │ Auto-fix missing test steps │ │
│ → Explores codebase │ └──────────────────────────────────┘ │
│ → Generates PRD │ ↓ │
│ │ ┌─ loop (per story) ───────────────┐ │
│ ENHANCE AS YOU LEARN │ │ │ │
│ → Add signs when Ralph repeats │ │ Read prd.json → get next story │ │
│ the same mistake │ │ Load PROMPT.md, signs, config │ │
│ → Tune timeouts, retries, checks │ │ Load last_failure.txt (if retry) │ │
│ → Refine test commands for your │ │ Build prompt with full context │ │
│ stack │ │ Spawn Claude → write code │ │
│ │ │ │ │
│ (OPTIONAL) CUSTOMIZE YOUR LOOP │ │ code-check: │ │
│ /my-dna → your coding style │ │ [1] Lint │ │
│ /styleguide → UI consistency │ │ [2] Tests │ │
│ /sign → teach patterns │ │ [3] PRD test steps │ │
│ config.json → tune your setup │ │ [4] API smoke │ │
│ │ │ [5] Frontend smoke │ │
│ │ │ │ │
│ │ │ Pass → commit, next story │ │
│ │ │ Fail → save to last_failure.txt, │ │
│ │ │ retry │ │
│ │ └──────────────────────────────────┘ │
│ │ │
└────────────────────────────────────────┴─────────────────────────────────────────┘
Terminal 1 is where you shape what gets built and how Ralph builds it. Terminal 2 is where Ralph executes autonomously.
Your loop gets smarter over time. When Ralph struggles with something, add a sign. When tests flake, tune the config. The customization never really stops—it's how you make Ralph work for your project.
Prerequisites: Node.js 18+, Claude Code CLI, jq (brew install jq)
npm install agentic-loop
npx agentic-loop setupTerminal 1 - Claude Code:
claude --dangerously-skip-permissions
/tour # Guided walkthrough (recommended first time)
/idea 'your feature' # Generate a PRDTerminal 2 - Ralph Loop:
npx agentic-loop run # Execute PRDs autonomouslyTip: Use two terminals. Plan with Claude in one, run Ralph in the other.
- Beginners Guide - New to this? Start here (no coding experience required)
- PRD Check - Story validation before coding starts
- Code Check - Verification pipeline after each story
- Customization - Personalization and guardrails
- How Ralph Works - Architecture, config, full reference
- Cheatsheet - All commands at a glance
- Hooks Reference - Pre-commit and Claude Code hooks
- Loopgram - Telegram bot for mobile idea capture and loop monitoring
- 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