Ralph Loop
A long-running AI agent loop that codes for days
Table of contents
What is Ralph Loop?
Ralph Loop is a long-running AI agent loop that automates software development by iterating through a task list until the job is done. Based on the "Ralph Wiggum" technique—relentless persistence over single-shot perfection—it runs your favorite agentic CLI inside Docker Sandboxes, works through tasks one by one, verifies each result, commits, and keeps going. Installed with a single npx @pageai/ralph-loop, it turns unstructured requirements into a durable PRD and task list, then lets the agent code for hours (or days) unattended while you walk away and come back to a stack of commits.
Key Features
- PRD-driven loop: Generate a PRD and task list from raw requirements so the loop has a durable source of truth instead of a single fragile prompt.
- Task lookup table: Per-task specs with detailed steps that scale to hundreds of tasks without losing context between iterations.
- Docker Sandboxes per agent: Deterministic, isolated, reusable sandboxes that are stopped cleanly on exit for safer autonomous execution.
- Multi-agent ready: Works with Claude, Codex, Cursor, Copilot, Gemini, and opencode out of the box—pass agent-specific flags through the same script.
- Live observability: Step detection, stream preview, screenshot capture, full history logs, and per-iteration timing while the loop runs.
- Steerable mid-flight: Edit
.agent/STEERING.mdwhile the loop is running and Ralph reads it each iteration to prioritize critical work. - Verification-first iterations: Each iteration runs tests, linting, and type checks, then commits—so "done" means actually verified, not just declared.
Who Can Benefit from Ralph Loop
- Indie hackers & solo builders: Makers who want to ship features overnight by handing a well-defined task list to an agent that keeps working unattended.
- Engineers tackling large refactors: Developers running repetitive, well-scoped migrations or refactors that benefit from automated verification on every step.
- AI tooling enthusiasts: People experimenting with autonomous coding agents who want a hackable, transparent loop rather than a black box.
- Teams standardizing agent workflows: Groups that want PRD generation, task breakdown, and sandboxed execution wrapped into one reproducible script.
- Multi-CLI users: Developers who switch between Claude, Codex, Cursor, Gemini, and others and want one loop that drives them all.
What Makes Ralph Loop Unique
- "A Ralph implementation that works": A hackable shell script grounded in the original Ralph Wiggum principles—fresh contexts and clear, verifiable feedback each iteration.
- Built for unattended, long-running work: Designed to run for hours or days across hundreds of tasks, not just a single short agentic session.
- Sandbox-native security: Runs agents inside Docker Sandboxes (isolated microVMs), so bypass-permissions / YOLO mode stays contained instead of touching your host.
- Observability baked in: Live stream preview, step detection, screenshots, timing, and full per-iteration logs give real traceability into what the agent did.
- Open and hackable: MIT-licensed and intentionally simple to modify for your language, framework, ports, and testing setup.
Pros
- Genuinely long-running: Keeps iterating until tasks pass or the iteration limit is reached, enabling autonomous coding sessions that last hours.
- Open source & customizable: MIT-licensed with a hackable
ralph.shyou can adapt to your stack, agent, and verification commands. - Strong safety model: Docker Sandboxes isolate each agent run, making aggressive permissions far safer than running on your host machine.
- Multi-agent flexibility: One workflow supports Claude, Codex, Cursor, Copilot, Gemini, and opencode without rewriting the script.
- Verification & traceability: Tests, linting, type checks, screenshots, and per-iteration history logs make progress auditable instead of opaque.
- Quick to start: A single
npx @pageai/ralph-loopinstalls the loop into an existing project.
Cons
- Setup overhead: Requires Docker Sandboxes plus an authenticated agent CLI, so the initial environment setup is more involved than a plain prompt.
- Usage costs add up: Long, unattended runs consume meaningful agent/API usage, so cost management matters for multi-hour loops.
- Needs good inputs: Results depend heavily on a well-structured PRD, task list, and reliable tests—blank-slate projects without verification fare worse.
- Still needs review: Autonomous output should be reviewed before shipping; it accelerates work but isn't a hands-off guarantee for production-critical code.
Links
Summary
Ralph Loop is a hackable, long-running AI agent loop that turns requirements into a PRD and task list, then keeps coding through them inside Docker Sandboxes until the work is verifiably done. With multi-agent support, live observability, mid-flight steering, and an open MIT license, it's a practical way to put autonomous coding agents to work—point it at a task list, walk away, and come back to a stack of reviewed-ready commits.