Ralph Loop by PageAI workflow
A Ralph loop for long tasks: an agent in a Docker sandbox works through a PRD task list, checks each task with tests and commits until the list is done
- 333 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent works without permission prompts: it edits code, installs packages, runs the app and tests and commits, and only the sandbox limits it
- The loop runs for hours and days and spends subscription limits or API key money on every iteration
- The agent sees the project's sources and environment variables: in the description's example Supabase and Stripe keys are available to it
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add workflows/ralph-loop-by-pageaiDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent works without permission prompts: it edits code, installs packages, runs the app and tests and commits, and only the sandbox limits it
- The loop runs for hours and days and spends subscription limits or API key money on every iteration
- The agent sees the project's sources and environment variables: in the description's example Supabase and Stripe keys are available to it
This is third-party code. Review the repository files before installing.
What it does
Ralph Loop is a kit for autonomous development: the `ralph.sh` script launches the agent over and over with a clean context and makes it work through a task list until everything is done or the iterations run out. The `npx @pageai/ralph-loop` command creates an `.agent` folder in the project with a prompt, a task file, templates, a log and shared skills. First you describe the requirements, and the `prd-creator` skill turns them into a PRD and splits it into tasks: a summary table in `tasks.json` and a `TASK-{ID}.json` file with steps for each. On each iteration the agent takes the highest-priority unfinished task, carries out its steps and writes a unit test, for interface tasks it runs a Playwright smoke test and saves a screenshot. Then it runs `eslint --fix`, `prettier --write`, `tsc` and tests across the project. When everything passes it marks the task done, adds to the log and makes a commit in Conventional Commits format. The prompt forbids the agent to push changes to a remote repository (`git push`). By default the agent works in Docker Sandboxes, isolated microVMs, with the mode that skips permission prompts: that is the reason the sandbox is needed. Besides Claude Code, Codex, Copilot, Cursor, Gemini and OpenCode are supported and selected with the `--agent` key. The `.agent/STEERING.md` file lets you add urgent work in the middle of a run, and the agent does it before the tasks. The agent reports status with tags: `COMPLETE`, `BLOCKED` or `DECIDE`, matching exit codes 0, 2 and 3.
Who it is for. For TypeScript web developers who want to hand an agent a large task list to run for hours or days and get commits with tests.
Good fit when
- You have requirements or a PRD of a few dozen tasks and want an agent to run through them without your involvement at every step
- The loop must run in an isolated sandbox rather than the main system because the agent works without permission prompts
- You want a trace of the agent's work: a log, screenshots, output history for every iteration and a commit per task
- A blocker appeared mid-run and you need to add urgent work through `.agent/STEERING.md`
- The project is already on React, Next.js or TanStack with Vitest and Playwright, as the kit assumes
Not a fit when
- There are no automated tests and nothing to verify the agent's work: the author makes verification the condition under which the loop works at all
- You cannot or do not want to install Docker Sandboxes and the `sbx` CLI: the script is built on them by default
- The project is not TypeScript: the prompt and checks are tied to Playwright, Vitest, `tsc`, ESLint and Prettier and would need rewriting
- The tasks are few and small: the overhead of a PRD, task splitting and a sandbox pays off only on a large list
- You want a simple loop without a sandbox and bundled skills: the catalog has Ralph by snarktank
Example request
Use the prd-creator skill: here are the requirements for an expense tracking service for freelancers on React and Supabase, write a PRD and a task list for RalphLimitations
- The script assumes Playwright, Vitest, TypeScript, ESLint and Prettier are installed. For another language or framework you edit `.agent/PROMPT.md`: ports, start commands and checks.
- Docker Sandboxes and a login to the agent are required. OAuth login inside the sandbox sometimes does not persist, and an API key helps then, but the author calls it usually more expensive and does not recommend it.
- The sandbox blocks outbound HTTP and HTTPS by default. If a package install or an API call fails, access is granted with `sbx policy allow network`, and the author advises lifting the filter completely only rarely.
- The author asks you to review each task individually before starting the loop. The first iteration goes to preparing the sandbox, the author warns of five minutes.
- The project has a documentation site and a video walkthrough. MIT license.
How to disable. Stop the loop with a double Ctrl+C: Ralph stops only the sandbox of the current run. Then delete the `.agent` folder and the `ralph.sh` file from the project, and find the unneeded sandbox with `sbx ls`. Commits the agent already made stay in the git history.
FAQ
What does each iteration of the loop do?
The agent finds the highest-priority task with a not-passed status in `.agent/tasks.json`, reads its `TASK-{ID}.json` file, carries out the steps, runs tests, the linter and the type check, marks the task, takes a screenshot and commits. The loop repeats until every task passes or the iteration limit is reached. The default is ten, and the number is set with the `-n` key.
Why is a Docker sandbox needed?
The agent is asked to enable the mode that skips permission prompts, and the author states that this is exactly why the sandbox is needed. Docker Sandboxes runs the agent in an isolated microVM. Each session gets a name like `ralph-<agent>-<folder>-<hash>`, so different agents in one project get separate sandboxes.
Which agents are supported?
Claude Code by default, and also Codex, Copilot, Cursor, Gemini and OpenCode. You pick the agent with the `--agent` key, for example `./ralph.sh --agent codex`. Extra agent options are passed after the `--` separator, for example `--model gpt-5.3-codex`.
How do I step in when the agent gets stuck?
Write the urgent work into `.agent/STEERING.md`. The agent checks the file on every iteration and, if it holds critical work, skips tasks and does that first. If the agent needs human help, it prints a `BLOCKED` or `DECIDE` tag with an explanation, and the loop ends with code 2 or 3.
Which skills come in the kit?
Thirteen: `prd-creator`, `agent-browser`, `e2e-tester`, `frontend-testing`, `frontend-code-review`, `component-refactoring`, `shadcn`, `postgres`, `mysql`, `vitest-best-practices`, `vercel-react-best-practices`, `web-design-guidelines` and `skill-creator`. They live in `.agent/skills/` and are duplicated by symlinks for Claude Code, Codex, Cursor and the shared `.agents` folder.
What if packages will not install in the sandbox?
Grant the sandbox access to the domains it needs. For example, `sbx policy allow network <name> "*.npmjs.org,github.com"` allows package registries and GitHub, and `sbx policy log` shows the connection history. Domain matching is exact: subdomains must be listed separately.
Discussion
No questions or reviews yet.
Related
WorkflowsThe ralph command repeats one prompt for Claude Code, Codex, Cursor Agent or OpenCode until a completion tag appears in the reply
A CLI orchestrator that loops Claude Code, Codex, Gemini CLI and other agents until a task is done and blocks incomplete work with tests and lint
Autonomous plan execution task by task: each task in a fresh Claude Code or Codex session, then a multi-pass review. Written in Go
One runtime for Claude Code, Codex, OpenCode and more: a run counts as done only when checks the agent did not write pass
The author's personal Claude Code toolbox: meta-prompt and todo commands, skills to create skills, hooks and MCP servers, auditors and a Ralph loop
A team of AI agents from one request: it plans the task, writes code in parallel branches, tests, reviews and opens a pull request
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Ralph Loop by PageAI (this entry) | no | 333 | ||
| Ralph | no | 22,083 | a Bash loop that restarts Claude Code or Amp with a clean context until all PRD stories pass their checks, plus two PRD skills | |
| Ralphy | no | 2,981 | a CLI that runs Claude Code, Codex, OpenCode and other agents in a loop over a task list or PRD until everything is done | |
| Ralph Orchestrator | no | not required | 3,190 | a CLI orchestrator that runs Claude Code, Codex, Gemini CLI and other agents in a loop until the task is ready and blocks incomplete work with tests and a linter |
README in short
The description walks through four steps: preparing the project, installing Ralph, creating the PRD and tasks, and setting up the agent in Docker Sandboxes and running it. Then come the script keys, how an iteration works, a comparison with other implementations of the loop, steering through the urgent-work file, status tags and exit codes, the structure of the `.agent` folder, the list of skills and recommended Playwright and Vitest settings. The debugging section explains how to get into the sandbox, give it network access and move to API keys. Bash scripts with a shared library and a `RALPH.md` file sit alongside.