How to use the Ralph Persistence Loop agent skill

What the ralph skill makes the agent do

Ralph is a PRD-driven persistence loop. PRD stands for product requirements document, and here it is a prd.json file that lists user stories. The agent works through the stories one at a time and keeps iterating until all of them are marked as passing and have been verified by a reviewer.

Ralph combines session persistence, automatic retry on failure, structured story tracking and a verification step before completion. Its stated purpose is to stop partial work from being declared done: tests get skipped and edge cases get forgotten when there is no checklist and no check.

• Story tracking: each user story has acceptance criteria, and the agent checks each one before marking the story complete.
• Progress notes: learnings across iterations are tracked in progress.txt.
• Verification: the verify step runs feedback commands such as build, test and lint.
• Reviewer sign-off: a separate reviewer (architect, critic or codex) checks the work before the task is finished.

Install the ralph skill from a ZIP file

Download the ZIP for the ralph skill from this page. Agent skills are folders that contain a SKILL.md file, and the ZIP holds the ralph skill's SKILL.md.

You can install it in one of two places. For a personal install, unzip it into your ~/.claude/skills/ folder. To limit it to one project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps instead of a folder on disk, you can upload the ZIP under Settings → Capabilities → Skills.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your repository
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Install the oh-my-claudecode toolkit and the omc command

The skill depends on the oh-my-claudecode toolkit and its omc command-line tool. Ralph calls omc ralph verify to run feedback checks and omc ralph afk for headless runs, so the skill will not do its full job without them. The skill file does not spell out the toolkit's installation steps, so follow the oh-my-claudecode project's own documentation for that part.

The skill also needs a repository that has build, test or lint scripts, or a feedbackCommands list in the PRD. Without either, there is nothing for the verify step to run.

• oh-my-claudecode toolkit with the omc command-line tool
• A repository with build, test or lint scripts, or a feedbackCommands list in the PRD
• Optional: codex access if you use --critic=codex

Trigger ralph with natural requests

You do not need special syntax to start the loop. The skill is meant to be triggered when you ask the agent to keep going on a task that has to be finished. The skill's own list of trigger phrases includes the word ralph, along with phrases such as don't stop, must complete, finish this and keep going until done.

Use it when the task needs guaranteed completion with checks, when it may take several rounds, or when you want reviewer sign-off. Describe the task clearly and say that it must be completed.

You can also add flags to the request. --critic=architect, --critic=critic or --critic=codex picks the completion reviewer for that run, and architect is the default. --no-deslop skips the cleanup pass after review, which the skill says to use only when cleanup is out of scope.

• Example phrasing: 'ralph: add CSV export to the reports page. It must complete, with tests passing.'
• Example phrasing: 'Keep going until done: migrate the auth module and make sure the build and lint pass.'
• Reviewer choice: add --critic=codex to the request to use codex as the reviewer.

Understand what happens during a run

On the first iteration, before choosing a story, the agent records a feedback baseline with omc ralph verify and the --write-baseline flag. Later checks run omc ralph verify and act on its exit code: 0 means pass, and 1 means new failures that must be fixed. The skill says the agent must not run the test suite and judge the output by eye, because that is the failure the gate exists to prevent.

The PRD can list feedback commands in a feedbackCommands array, such as npm run build, npm test and npm run lint. If that list is missing, the skill detects them from the repository's package scripts.

The prd.json file is created automatically when Ralph starts if none exists. In session-based runs its active copy lives under .omc/state/sessions/ with the session ID in the path.

• Exit code 0: pass; failures present in the baseline are recorded as warnings, not story failures.
• Exit code 1: new failures that the agent must fix before continuing.
• feedbackCommands example: ["npm run build", "npm test", "npm run lint"] in the PRD.

Safety notes before you run ralph unattended

Ralph runs scripts, which means it executes commands in your repository. It does not use the network, according to the skill's metadata. Because the loop repeats and edits code across iterations, you should be careful with unattended runs.

The skill's own guidance warns that headless mode (omc ralph afk) and repeated edits can change a repository without review. Keep the work in version control, review the diff afterwards, and avoid unattended runs on code you cannot easily roll back.

• Runs scripts: yes. Commands from your package scripts and the feedbackCommands list will run.
• Uses network: no, according to the skill metadata.
• Unattended runs: omc ralph afk can modify code repeatedly without a human watching, so review the results afterwards.
• Use a clean git branch so you can revert the changes easily.

Tips for getting good results

Write acceptance criteria that can be tested. The skill checks each story against them, so vague criteria give the reviewer nothing to verify. Keep stories small enough that one iteration can finish one of them.

Pick the repository quality class deliberately. The PRD carries a repoQualityClass value of prototype, production or library, and production is the default. Choosing the right class affects how strict the acceptance checks are.

Do not use ralph for a quick one-line fix or for exploratory planning. The skill's guidance points those cases to other tools.

• Make each acceptance criterion specific and checkable.
• Set feedbackCommands explicitly if your repository's scripts are unclear.
• Use the plan skill to explore before committing to a task.
• Use autopilot if you want a full pipeline from idea to code.