Ralph is an autonomous AI agent loop that runs Codex CLI repeatedly until all PRD items are complete. Each iteration is a fresh Codex instance with clean context. Memory persists via git history, progress.txt, and prd.json. (Amp is still supported as an optional engine.)
Based on Geoffrey Huntley's Ralph pattern.
Read my in-depth article on how I use Ralph
- Codex CLI installed and authenticated
codex loginfor local use, or setCODEX_API_KEYin CI
jqinstalled (brew install jqon macOS)- A git repository for your project
- (Optional) Amp CLI if you want to use the legacy engine
Copy the ralph files into your project:
# From your project root
mkdir -p scripts/ralph
cp /path/to/ralph/ralph.sh scripts/ralph/
cp /path/to/ralph/prompt.md scripts/ralph/
chmod +x scripts/ralph/ralph.shCopy the skills to your Codex config for use across all projects:
cp -r .codex/skills/ralph-codex ~/.codex/skills/
# Optional: make the PRD and PRD->JSON converter skills available to Codex
cp -r skills/prd ~/.codex/skills/
cp -r skills/ralph ~/.codex/skills/Add to ~/.config/amp/settings.json:
{
"amp.experimental.autoHandoff": { "context": 90 }
}This enables automatic handoff when context fills up, allowing Ralph to handle large stories that exceed a single context window.
Codex automatically discovers skills from:
.codex/skillsin your repo~/.codex/skillsglobally
Optional: install curated skills with the $skill-installer skill (restart Codex after installing):
Load the $skill-installer skill and install [skill-name] from openai/skills
Use the PRD skill to generate a detailed requirements document (install skills/prd into ~/.codex/skills or copy into .codex/skills first):
Load the prd skill and create a PRD for [your feature description]
Answer the clarifying questions. The skill saves output to tasks/prd-[feature-name].md.
Use the Ralph skill to convert the markdown PRD to JSON (install skills/ralph into ~/.codex/skills or copy into .codex/skills first):
Load the ralph skill and convert tasks/prd-[feature-name].md to prd.json
This creates prd.json with user stories structured for autonomous execution.
./scripts/ralph/ralph.sh [max_iterations]Default is 10 iterations.
Codex runs in read-only mode by default. For edits, enable full auto:
RALPH_CODEX_FULL_AUTO=1 ./scripts/ralph/ralph.sh [max_iterations]You can override the sandbox policy if you need broader access:
RALPH_CODEX_SANDBOX=workspace-write ./scripts/ralph/ralph.sh [max_iterations]To use Amp instead of Codex:
RALPH_ENGINE=amp ./scripts/ralph/ralph.sh [max_iterations]Ralph will:
- Create a feature branch (from PRD
branchName) - Pick the highest priority story where
passes: false - Implement that single story
- Run quality checks (typecheck, tests)
- Commit if checks pass
- Update
prd.jsonto mark story aspasses: true - Append learnings to
progress.txt - Repeat until all stories pass or max iterations reached
| File | Purpose |
|---|---|
ralph.sh |
The bash loop that spawns fresh Codex instances |
prompt.md |
Instructions given to each Codex instance |
prd.json |
User stories with passes status (the task list) |
prd.json.example |
Example PRD format for reference |
progress.txt |
Append-only learnings for future iterations |
.codex/skills/ralph-codex/ |
Repo-local Codex skill for Ralph conventions |
skills/prd/ |
Skill for generating PRDs (copy to ~/.codex/skills if using Codex) |
skills/ralph/ |
Skill for converting PRDs to JSON (copy to ~/.codex/skills if using Codex) |
flowchart/ |
Interactive visualization of how Ralph works |
View Interactive Flowchart - Click through to see each step with animations.
The flowchart/ directory contains the source code. To run locally:
cd flowchart
npm install
npm run devEach iteration spawns a new Codex instance with clean context. The only memory between iterations is:
- Git history (commits from previous iterations)
progress.txt(learnings and context)prd.json(which stories are done)
Each PRD item should be small enough to complete in one context window. If a task is too big, the LLM runs out of context before finishing and produces poor code.
Right-sized stories:
- Add a database column and migration
- Add a UI component to an existing page
- Update a server action with new logic
- Add a filter dropdown to a list
Too big (split these):
- "Build the entire dashboard"
- "Add authentication"
- "Refactor the API"
After each iteration, Ralph updates the relevant AGENTS.md files with learnings. This is key because Codex automatically reads these files, so future iterations (and future human developers) benefit from discovered patterns, gotchas, and conventions.
Examples of what to add to AGENTS.md:
- Patterns discovered ("this codebase uses X for Y")
- Gotchas ("do not forget to update Z when changing W")
- Useful context ("the settings panel is in component X")
Ralph only works if there are feedback loops:
- Typecheck catches type errors
- Tests verify behavior
- CI must stay green (broken code compounds across iterations)
Frontend stories must include "Verify in browser using dev-browser skill" in acceptance criteria. Ralph will use the dev-browser skill to navigate to the page, interact with the UI, and confirm changes work.
When all stories have passes: true, Ralph outputs <promise>COMPLETE</promise> and the loop exits.
Check current state:
# See which stories are done
cat prd.json | jq '.userStories[] | {id, title, passes}'
# See learnings from previous iterations
cat progress.txt
# Check git history
git log --oneline -10Edit prompt.md to customize Ralph's behavior for your project:
- Add project-specific quality check commands
- Include codebase conventions
- Add common gotchas for your stack
Ralph automatically archives previous runs when you start a new feature (different branchName). Archives are saved to archive/YYYY-MM-DD-feature-name/.