by PageAI-Pro
A long-running AI agent loop. Ralph automates software development tasks by iteratively working through a task list until completion.
# Add to your Claude Code skills
git clone https://github.com/PageAI-Pro/ralph-loopRalph is a long-running AI agent loop. Ralph automates software development tasks by iteratively working through a task list until completion. This allows for long running agent loops, effectively enabling AI to code for days at a time.
This is an implementation that actually works, containing a hackable script so you can configure it to your env and favorite agentic AI CLI. It's set up by default to use Claude Code in a Docker sandbox, but supports many other agentic AI CLIs.
No comments yet. Be the first to share your thoughts!
I recommend using a CLI to bootstrap your project with the necessary tools and dependencies, e.g.:
npx @tanstack/cli create lib --add-ons eslint,form,tanstack-query,nitro --no-git
If you must start from a blank slate, which is not recommended, see Starting from scratch. You can also go for a more barebone start by running
npx create-vite@latest src --template react-ts
Run this in your project's directory to install Ralph.
npx @pageai/ralph-loop
Use the prd-creator skill to generate a PRD from your requirements.
Open up Claude Code or Cursor etc. and prompt it with your requirements. Like so:
Use the prd-creator skill to help me create a PRD and task list for the below requirements.
An app is already set up with React, Tailwind CSS and TypeScript.
Requirements:
- A SaaS product that helps users manage their finances.
- Target audience: Small business owners and freelancers.
- Core features:
- Track income and expenses.
- Create and send invoices.
- Track payments and receipts.
- Generate reports and insights.
- Connect to bank accounts and credit cards.
- Connect to accounting software.
- Connect to payment processors.
- Use the shadcn/ui library for components.
- Integrate with Stripe for payments.
- Use Supabase for database.
- You can find env variables in the .env.example file: SUPABASE_URL, SUPABASE_PUBLISHABLE_KEY, STRIPE_SECRET_KEY, etc. are available in the runtime.
// etc.
Check out the video for a more realistic example on how to write requirements.
.env and add it to .gitignore/docs and mention them in the requirementsThen, follow the Skill's instructions and verify the PRD and then tasks. It is highly recommended that you review individual task requirements before starting the loop. Review EACH TASK INDIVIDUALLY.
Authenticate inside the Docker sandbox before running Ralph. Run:
docker sandbox run claude .
And follow the instructions to log in into Claude Code.
👉 Answer "Yes" to Bypass Permissions mode, that's the exact reason why you are using the Docker sandbox.
If you want to use a different agentic CLI, see Running with a different agentic CLI.
./ralph.sh -n 50 # Run Ralph Loop with 50 iterations
✍️ Note: the first iteration will be spent on ensuring the sandbox environment is set up correctly. Expect 5 minutes to complete.
# Run the agent loop (default: 10 iterations)
./ralph.sh
# Run with custom iteration limit
./ralph.sh 5
./ralph.sh -n 5
./ralph.sh --max-iterations 5
# Run exactly one iteration
./ralph.sh --once
# Show help
./ralph.sh --help
NB: you might need to run
chmod +x ralph.shto make the script executable.
The default "mode" is "implementation". Depending on your use case, you might want to change
.agent/PROMPT.mdto a different mode, e.g. "refactor", "review", "test" etc.
⚠️ If you want to use a different language or testing framework, see below.
This script assumes the following are installed:
If you'd like to use a different language, testing framework etc. please adjust .agent/PROMPT.md to reflect your setup, server ports and startup commands etc.
👉 The loop is controlled by this prompt, which will be sent to the agent each iteration.
Each iteration, Ralph will:
.agent/tasks.json.agent/tasks/TASK-{ID}.jsonThis was kept hackable so you can make it your own. The script follows the original concepts of the Ralph Wiggum Loop, working with fresh contexts and providing clear verifiable feedback.
It also works generically with any task set.
In some cases, you might notice the agent is having trouble, slowed down or struggling to overcome a blocker.
While the loop is running, you can edit the .agent/STEERING.md file to add critical work that needs to be done before the loop can continue.
The agent will check this file each iteration and if it finds any critical work, it will skip tasks and complete the critical work first.
The ralph.sh script is designed to be hackable.
It is configured to use Claude Code in a Docker sandbox by default, but with a one-liner change you can change it to use any other agentic AI CLI.
Check the ralph.sh script around # This is the main command loop. for the main command loop.
NB: skills are supported by all major agentic AI CLIs via symlinks.
Ralph uses semantic tags to communicate status:
<promise>COMPLETE</promise> - All tasks finished successfully<promise>BLOCKED:reason</promise> - Agent needs human help<promise>DECIDE:question</promise> - Agent needs a decision