# Send Ralph Loops to your agent Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually. ## Fast path - Download the package from Yavira. - Extract it into a folder your agent can access. - Paste one of the prompts below and point your agent at the extracted folder. ## Suggested prompts ### New install ```text I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete. ``` ### Upgrade existing ```text I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run. ``` ## Machine-readable fields ```json { "schemaVersion": "1.0", "item": { "slug": "ralph-loops", "name": "Ralph Loops", "source": "tencent", "type": "skill", "category": "AI 智能", "sourceUrl": "https://clawhub.ai/qlifebot-coder/ralph-loops", "canonicalUrl": "https://clawhub.ai/qlifebot-coder/ralph-loops", "targetPlatform": "OpenClaw" }, "install": { "downloadUrl": "/downloads/ralph-loops", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=ralph-loops", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "packageFormat": "ZIP package", "primaryDoc": "SKILL.md", "includedAssets": [ "SETUP.md", "SKILL.md", "dashboard/lib/cost-calculator.mjs", "dashboard/lib/loop-detector.mjs", "dashboard/lib/ralph-reader.mjs", "dashboard/lib/transcript-reader.mjs" ], "downloadMode": "redirect", "sourceHealth": { "source": "tencent", "slug": "ralph-loops", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-05-03T08:58:38.262Z", "expiresAt": "2026-05-10T08:58:38.262Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=ralph-loops", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=ralph-loops", "contentDisposition": "attachment; filename=\"ralph-loops-1.0.2.zip\"", "redirectLocation": null, "bodySnippet": null, "slug": "ralph-loops" }, "scope": "item", "summary": "Item download looks usable.", "detail": "Yavira can redirect you to the upstream package for this item.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/ralph-loops" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] } }, "links": { "detailUrl": "https://openagent3.xyz/skills/ralph-loops", "downloadUrl": "https://openagent3.xyz/downloads/ralph-loops", "agentUrl": "https://openagent3.xyz/skills/ralph-loops/agent", "manifestUrl": "https://openagent3.xyz/skills/ralph-loops/agent.json", "briefUrl": "https://openagent3.xyz/skills/ralph-loops/agent.md" } } ``` ## Documentation ### Ralph Loops Skill First time? Read SETUP.md first to install dependencies and verify your setup. Autonomous AI agent loops for iterative development. Based on Geoffrey Huntley's Ralph Wiggum technique, as documented by Clayton Farr. Script: skills/ralph-loops/scripts/ralph-loop.mjs Dashboard: skills/ralph-loops/dashboard/ (run with node server.mjs) Templates: skills/ralph-loops/templates/ Archive: ~/clawd/logs/ralph-archive/ ### Claude Code Version Compatibility Claude Code 2.1.29 has a critical bug that spawns orphaned sub-agents consuming 99% CPU. Iterations fail with "exit code null" on first run. Fix: Downgrade to 2.1.25: npm install -g @anthropic-ai/claude-code@2.1.25 Verify: claude --version # Should show 2.1.25 This was discovered 2026-02-01. Check if newer versions fix the issue before upgrading. ### ⚠️ Don't Block the Conversation! When running a Ralph loop, don't monitor it synchronously. The loop runs as a separate Claude CLI process — you can keep chatting. ❌ Wrong (blocks conversation): Start loop → sleep 60 → poll → sleep 60 → poll → ... (6 minutes of silence) ✅ Right (stays responsive): Start loop → "It's running, I'll check periodically" → keep chatting → check on heartbeats How to monitor without blocking: Start the loop with node ralph-loop.mjs ... (runs in background) Tell human: "Loop running. I'll check progress periodically or you can ask." Check via process poll when asked or during heartbeats Use the dashboard at http://localhost:3939 for real-time visibility The loop is autonomous — that's the whole point. Don't babysit it at the cost of ignoring your human. ### Trigger Phrases When human says: PhraseAction"Interview me about system X"Start Phase 1 requirements interview"Start planning system X"Run ./loop.sh plan (needs specs first)"Start building system X"Run ./loop.sh build (needs plan first)"Ralph loop over X"ASK which phase (see below) ### When Human Says "Ralph Loop" — Clarify the Phase! Don't assume which phase. Ask: "Which type of Ralph loop are we doing? 1️⃣ Interview — I'll ask you questions to build specs (Phase 1) 2️⃣ Planning — I'll iterate on an implementation plan (Phase 2) 3️⃣ Building — I'll implement from a plan, one task per iteration (Phase 3) 4️⃣ Generic — Simple iterative refinement on a single topic" Then proceed based on their answer: ChoiceActionInterviewUse templates/requirements-interview.md protocolPlanningNeed specs first → run planning loop with PROMPT_plan.mdBuildingNeed plan first → run build loop with PROMPT_build.mdGenericCreate prompt file, run ralph-loop.mjs directly ### Generic Ralph Loop Flow (Phase 4) For simple iterative refinement (not full system builds): Clarify the task — What exactly should be improved/refined? Create a prompt file — Save to /tmp/ralph-prompt-.md Set completion criteria — What signals "done"? Run the loop: node skills/ralph-loops/scripts/ralph-loop.mjs \\ --prompt "/tmp/ralph-prompt-.md" \\ --model opus \\ --max 10 \\ --done "RALPH_DONE" Or spawn as sub-agent for long-running tasks ### Core Philosophy "Human roles shift from 'telling the agent what to do' to 'engineering conditions where good outcomes emerge naturally through iteration." — Clayton Farr Three principles drive everything: Context is scarce — With ~176K usable tokens from a 200K window, keep each iteration lean Plans are disposable — A drifting plan is cheaper to regenerate than salvage Backpressure beats direction — Engineer environments where wrong outputs get rejected automatically ### Three-Phase Workflow ┌─────────────────────────────────────────────────────────────────────┐ │ Phase 1: REQUIREMENTS │ │ Human + LLM conversation → JTBD → Topics → specs/*.md │ ├─────────────────────────────────────────────────────────────────────┤ │ Phase 2: PLANNING │ │ Gap analysis (specs vs code) → IMPLEMENTATION_PLAN.md │ ├─────────────────────────────────────────────────────────────────────┤ │ Phase 3: BUILDING │ │ One task per iteration → fresh context → backpressure → commit │ └─────────────────────────────────────────────────────────────────────┘ ### Phase 1: Requirements (Talk to Human) Goal: Understand what to build BEFORE building it. This is the most important phase. Use structured conversation to: Identify Jobs to Be Done (JTBD) What user need or outcome are we solving? Not features — outcomes Break JTBD into Topics of Concern Each topic = one distinct aspect/component Use the "one sentence without 'and'" test ✓ "The color extraction system analyzes images to identify dominant colors" ✗ "The user system handles authentication, profiles, and billing" → 3 topics Create Specs for Each Topic One markdown file per topic in specs/ Capture requirements, acceptance criteria, edge cases Template: templates/requirements-interview.md ### Phase 2: Planning (Gap Analysis) Goal: Create a prioritized task list without implementing anything. Uses PROMPT_plan.md in the loop: Study all specs Study existing codebase Compare specs vs code (gap analysis) Generate IMPLEMENTATION_PLAN.md with prioritized tasks NO implementation — planning only Usually completes in 1-2 iterations. ### Phase 3: Building (One Task Per Iteration) Goal: Implement tasks one at a time with fresh context. Uses PROMPT_build.md in the loop: Read IMPLEMENTATION_PLAN.md Pick the most important task Investigate codebase (don't assume not implemented) Implement Run validation (backpressure) Update plan, commit Exit → fresh context → next iteration Key insight: One task per iteration keeps context lean. The agent stays in the "smart zone" instead of accumulating cruft. Why fresh context matters: No accumulated mistakes — Each iteration starts clean; previous errors don't compound Full context budget — 200K tokens for THIS task, not shared with finished work Reduced hallucination — Shorter contexts = more grounded responses Natural checkpoints — Each commit is a save point; easy to revert single iterations ### File Structure project/ ├── loop.sh # Ralph loop script ├── PROMPT_plan.md # Planning mode instructions ├── PROMPT_build.md # Building mode instructions ├── AGENTS.md # Operational guide (~60 lines max) ├── IMPLEMENTATION_PLAN.md # Prioritized task list (generated) └── specs/ # Requirement specs ├── topic-a.md ├── topic-b.md └── ... ### File Purposes FilePurposeWho Createsspecs/*.mdSource of truth for requirementsHuman + Phase 1PROMPT_plan.mdInstructions for planning modeCopy from templatePROMPT_build.mdInstructions for building modeCopy from templateAGENTS.mdBuild/test/lint commandsHuman + RalphIMPLEMENTATION_PLAN.mdTask list with prioritiesRalph (Phase 2) ### Project Organization (Systems) For Clawdbot systems, each Ralph project lives in /systems//: systems/ ├── health-tracker/ # Example system │ ├── specs/ │ │ ├── daily-tracking.md │ │ └── test-scheduling.md │ ├── PROMPT_plan.md │ ├── PROMPT_build.md │ ├── AGENTS.md │ ├── IMPLEMENTATION_PLAN.md # ← exists = past Phase 1 │ └── src/ └── activity-planner/ ├── specs/ # ← empty = still in Phase 1 └── ... ### Phase Detection (Auto) Detect current phase by checking what files exist: What ExistsCurrent PhaseNext ActionNothing / empty specs/Phase 1: RequirementsRun requirements interviewspecs/*.md but no IMPLEMENTATION_PLAN.mdReady for Phase 2Run ./loop.sh planspecs/*.md + IMPLEMENTATION_PLAN.mdPhase 2 or 3Review plan, run ./loop.sh buildPlan shows all tasks completeDoneArchive or iterate Quick check: # What phase are we in? [ -z "$(ls specs/ 2>/dev/null)" ] && echo "Phase 1: Need specs" && exit [ ! -f IMPLEMENTATION_PLAN.md ] && echo "Phase 2: Need plan" && exit echo "Phase 3: Ready to build (or done)" ### JTBD Breakdown The hierarchy matters: JTBD (Job to Be Done) └── Topic of Concern (1 per spec file) └── Tasks (many per topic, in IMPLEMENTATION_PLAN.md) Example: JTBD: "Help designers create mood boards" Topics: Image collection → specs/image-collection.md Color extraction → specs/color-extraction.md Layout system → specs/layout-system.md Sharing → specs/sharing.md Tasks: Each spec generates multiple implementation tasks ### Topic Scope Test Can you describe the topic in one sentence without "and"? If you need "and" or "also", it's probably multiple topics. Split it. When to split: Multiple verbs in the description → separate topics Different user personas involved → separate topics Could be implemented by different teams → separate topics Has its own failure modes → probably its own topic Example split: ❌ "User management handles registration, authentication, profiles, and permissions" ✅ Split into: - "Registration creates new user accounts from email/password" - "Authentication verifies user identity via login flow" - "Profiles let users view and edit their information" - "Permissions control what actions users can perform" Counter-example (don't split): ✅ Keep together: "Color extraction analyzes images and returns dominant color palettes" Why: "analyzes" and "returns" are steps in one operation, not separate concerns. ### Backpressure Mechanisms Autonomous loops converge when wrong outputs get rejected. Three layers: ### 1. Downstream Gates (Hard) Tests, type-checking, linting, build validation. Deterministic. # In AGENTS.md ## Validation - Tests: \`npm test\` - Typecheck: \`npm run typecheck\` - Lint: \`npm run lint\` ### 2. Upstream Steering (Soft) Existing code patterns guide the agent. It discovers conventions through exploration. ### 3. LLM-as-Judge (Subjective) For subjective criteria (tone, UX, aesthetics), use another LLM call with binary pass/fail. Start with hard gates. Add LLM-as-judge for subjective criteria only after mechanical backpressure works. ### Prompt Structure Geoffrey's prompts follow a numbered pattern: SectionPurpose0a-0dOrient: Study specs, source, current plan1-4Main instructions: What to do this iteration999+Guardrails: Invariants (higher number = more critical) ### The Numbered Guardrails Pattern Guardrails use escalating numbers (99999, 999999, 9999999...) to signal priority: 99999. Important: Capture the why in documentation. 999999. Important: Single sources of truth, no migrations. 9999999. Create git tags after successful builds. 99999999. Add logging if needed to debug. 999999999. Keep IMPLEMENTATION_PLAN.md current. Why this works: Visual prominence — Large numbers stand out, harder to skip Implicit priority — More 9s = more critical (like DEFCON levels in reverse) No collisions — Sparse numbering lets you insert new rules without renumbering Mnemonic — Claude treats these as invariants, not suggestions The "Important:" prefix is deliberate — it triggers Claude's attention. ### Key Language Patterns Use Geoffrey's specific phrasing — it matters: "study" (not "read" or "look at") "don't assume not implemented" (critical!) "using parallel subagents" / "up to N subagents" "only 1 subagent for build/tests" (backpressure control) "Ultrathink" (deep reasoning trigger) "capture the why" "keep it up to date" "resolve them or document them" ### 1. Set Up Project Structure mkdir -p myproject/specs cd myproject git init # Ralph expects git for commits # Copy templates cp .//templates/PROMPT_plan.md . cp .//templates/PROMPT_build.md . cp .//templates/AGENTS.md . cp .//templates/loop.sh . chmod +x loop.sh ### 2. Customize Templates (Required!) PROMPT_plan.md — Replace [PROJECT_GOAL] with your actual goal: # Before: ULTIMATE GOAL: We want to achieve [PROJECT_GOAL]. # After: ULTIMATE GOAL: We want to achieve a fully functional mood board app with image upload and color extraction. PROMPT_build.md — Adjust source paths if not using src/: # Before: 0c. For reference, the application source code is in \`src/*\`. # After: 0c. For reference, the application source code is in \`lib/*\`. AGENTS.md — Update build/test/lint commands for your stack. ### 3. Phase 1: Requirements Gathering (Don't Skip!) This phase happens WITH the human. Use the interview template: cat .//templates/requirements-interview.md The workflow: Discuss the JTBD (Job to Be Done) — outcomes, not features Break into Topics of Concern (each passes the "one sentence" test) Write a spec file for each topic: specs/topic-name.md Human reviews and approves specs Example output: specs/ ├── image-collection.md ├── color-extraction.md ├── layout-system.md └── sharing.md ### 4. Phase 2: Planning ./loop.sh plan Wait for IMPLEMENTATION_PLAN.md to be generated (usually 1-2 iterations). Review it — this is your task list. ### 5. Phase 3: Building ./loop.sh build 20 # Max 20 iterations Watch it work. Add backpressure (tests, lints) as patterns emerge. Check commits for progress. ### Loop Script Options ./loop.sh # Build mode, unlimited ./loop.sh 20 # Build mode, max 20 iterations ./loop.sh plan # Plan mode, unlimited ./loop.sh plan 5 # Plan mode, max 5 iterations Or use the Node.js wrapper for more control: node skills/ralph-loops/scripts/ralph-loop.mjs \\ --prompt "./PROMPT_build.md" \\ --model opus \\ --max 20 \\ --done "RALPH_DONE" ### When to Regenerate the Plan Plans drift. Regenerate when: Ralph is going off track (implementing wrong things) Plan feels stale or doesn't match current state Too much clutter from completed items You've made significant spec changes You're confused about what's actually done Just switch back to planning mode: ./loop.sh plan Regeneration cost is one Planning loop. Cheap compared to Ralph going in circles. ### Safety Ralph requires --dangerously-skip-permissions to run autonomously. This bypasses Claude's permission system entirely. Philosophy: "It's not if it gets popped, it's when. And what is the blast radius?" Protections: Run in isolated environments (Docker, VM) Only the API keys needed for the task No access to private data beyond requirements Restrict network connectivity where possible Escape hatches: Ctrl+C stops the loop; git reset --hard reverts uncommitted changes ### Cost Expectations Task TypeModelIterationsEst. CostGenerate planOpus1-2$0.50-1.00Implement simple featureOpus3-5$1.00-2.00Implement complex featureOpus10-20$3.00-8.00Full project buildoutOpus50+$15-50+ Tip: Use Sonnet for simpler tasks where plan is clear. Use Opus for planning and complex reasoning. ### Real-World Results From Geoffrey Huntley: 6 repos generated overnight at YC hackathon $50k contract completed for $297 in API costs Created entire programming language over 3 months ### Advanced: Running as Sub-Agent For long loops, spawn as sub-agent so main session stays responsive: sessions_spawn({ task: \`cd /path/to/project && ./loop.sh build 20 Summarize what was implemented when done.\`, label: "ralph-build", model: "opus" }) Check progress: sessions_list({ kinds: ["spawn"] }) sessions_history({ label: "ralph-build", limit: 5 }) ### Ralph keeps implementing the same thing Plan is stale → regenerate with ./loop.sh plan Backpressure missing → add tests that catch duplicates ### Ralph goes in circles Add more specific guardrails to prompts Check if specs are ambiguous Regenerate plan ### Context getting bloated Ensure one task per iteration (check prompt) Keep AGENTS.md under 60 lines Move status/progress to IMPLEMENTATION_PLAN.md, not AGENTS.md ### Tests not running Check AGENTS.md has correct validation commands Ensure backpressure section in prompt references AGENTS.md ### Projects Without Git The loop script expects git for commits and pushes. For projects without version control: Option 1: Initialize git anyway (recommended) git init git add -A git commit -m "Initial commit before Ralph" Option 2: Modify the prompts Remove git-related guardrails from PROMPT_build.md Remove the git push section from loop.sh Use file backups instead: add cp -r src/ backups/iteration-$ITERATION/ to loop.sh Option 3: Use tarball snapshots # Add to loop.sh before each iteration: tar -czf "snapshots/pre-iteration-$ITERATION.tar.gz" src/ ### Very Large Codebases For codebases with 100K+ lines: Reduce subagent parallelism: Change "up to 500 parallel Sonnet subagents" to "up to 50" in prompts Scope narrowly: Use focused specs that target specific directories Add path restrictions: In AGENTS.md, note which directories are in-scope Consider workspace splitting: Treat large modules as separate Ralph projects ### When Claude CLI Isn't Available The methodology works with any Claude interface: Claude API directly: # Replace loop.sh with API calls using curl or a script curl https://api.anthropic.com/v1/messages \\ -H "x-api-key: $ANTHROPIC_API_KEY" \\ -H "content-type: application/json" \\ -d '{"model": "claude-sonnet-4-20250514", "max_tokens": 8192, "messages": [...]}' Alternative agents: Aider: aider --opus --auto-commits Continue.dev: Use with Claude API key Cursor: Composer mode with PROMPT files as context The key principles (one task per iteration, fresh context, backpressure) apply regardless of tooling. ### Non-Node.js Projects Adapt AGENTS.md for your stack: StackBuildTestLintPythonpip install -e .pytestruff .Gogo build ./...go test ./...golangci-lint runRustcargo buildcargo testcargo clippyRubybundle installrspecrubocop Also update path references in prompts (src/* → your source directory). ### Learn More Geoffrey Huntley: https://ghuntley.com/ralph/ Clayton Farr's Playbook: https://github.com/ClaytonFarr/ralph-playbook Geoffrey's Fork: https://github.com/ghuntley/how-to-ralph-wiggum ### Credits Built by Johnathan & Q — a human-AI dyad. Twitter: @spacepixel ClawdHub: clawhub.ai/skills/ralph-loops ## Trust - Source: tencent - Verification: Indexed source record - Publisher: qlifebot-coder - Version: 1.0.2 ## Source health - Status: healthy - Item download looks usable. - Yavira can redirect you to the upstream package for this item. - Health scope: item - Reason: direct_download_ok - Checked at: 2026-05-03T08:58:38.262Z - Expires at: 2026-05-10T08:58:38.262Z - Recommended action: Download for OpenClaw ## Links - [Detail page](https://openagent3.xyz/skills/ralph-loops) - [Send to Agent page](https://openagent3.xyz/skills/ralph-loops/agent) - [JSON manifest](https://openagent3.xyz/skills/ralph-loops/agent.json) - [Markdown brief](https://openagent3.xyz/skills/ralph-loops/agent.md) - [Download page](https://openagent3.xyz/downloads/ralph-loops)