Ralph Loop Quickstart
https://github.com/coleam00/ralph-loop-quickstart- Category
- AI Agents
- Rank
- No. 1990Tools index
- Pricing
- Open Source
- Type
- TOOL
- Builder
- coleam00
- GitHub
- 159 stars
- Date
About
Quickstart for running the Ralph Wiggum agent loop properly — without depending on the Anthropic plugin.
What it does
It turns a defined product idea into an autonomous, task-by-task Claude Code workflow. An interactive planning command creates requirements and ordered tasks. A Bash script then starts a new Claude session for each task, while browser automation checks the application and an activity log records progress.
Why it's ranked here
This is a practical scaffold for tightly scoped prototypes because it combines planning, isolated agent sessions, visual checks, progress logs, and per-task commits. Its value depends heavily on task quality, however, and its completion mechanism trusts a text signal from the agent rather than independently checking every requirement.
What's good
Fresh context on every iteration limits accumulated prompt clutter. Tasks are intentionally atomic, ordered, and verifiable. The workflow also leaves useful review artifacts: browser screenshots, an activity log, task status changes, terminal output, and one Git commit per completed task. Default sandbox rules deny several sensitive or destructive operations.
Tradeoffs
It requires Claude Code, a globally installed browser automation CLI, and downloaded Chromium. The approach targets greenfield proofs of concept, not complex existing systems or ambiguous exploration. Command failures from Claude are tolerated by the loop, and completion depends on emitted text. Broad web fetching is allowed, while project-specific command permissions require careful inspection.
How to use it well
Use it for a small greenfield prototype whose features, dependencies, and finish conditions are already clear. Break work into single-iteration tasks, inspect the generated plan and permissions, then monitor the opening iterations. It does not replace production hardening, independent acceptance testing, architecture discovery, or the human judgment needed for unclear requirements.
Technical notes+
ralph.sh validates PROMPT.md and prd.md, creates activity.md and screenshots/ when absent, invokes claude -p once per iteration, captures failures with || true, and stops when output contains <promise>COMPLETE</promise>. PROMPT.md directs each session to select one failing task, run checks, verify through agent-browser, update status, log work, and commit. .claude/commands/create-prd.md generates prd.md and adjusts project commands and permissions. .claude/settings.json enables sandboxing, permits local binding, denies sensitive reads and destructive commands, and requires confirmation for pushes.
Observed
- Primary implementation
- Bash shell script with Markdown workflow templates and JSON configuration
- Interface
- Command-line workflow for Claude Code
- Required tools
- Claude Code, agent-browser CLI, and Chromium
- Verification surface
- Headless browser interaction, snapshots, screenshots, and console checks
- Execution model
- One fresh Claude Code context and one task per iteration
- Safety configuration
- Sandbox enabled with command allow, deny, and confirmation lists
- Repository structure
- No test directory appears in the provided repository tree
Read from README.md, ralph.sh, PROMPT.md, activity.md, .claude/settings.json, .claude/commands/create-prd.md, .claude/skills/agent-browser-skill/SKILL.md.
What it can do
Initialize Ralph Wiggum agent loop
Configuration parameters → Running agent loop instance
Run agent loop without Anthropic plugin dependency
Agent configuration and tasks → Executed agent operations
Setup quickstart environment
System requirements and dependencies → Configured runtime environment
Execute agent decision cycles
Task objectives and context → Agent decisions and actions
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.