Ralphing
Ralph is an autonomous AI coding loop that ships features while you sleep. Each iteration runs in a fresh context window, while memory persists through git history and text files.
When to Use
When the user wants to implement a multi-story feature autonomously, or mentions "ralph", "ralphing", or "autonomous loop".
Workflow
Step 1: Get the PRD
The user provides a PRD file, or you help them create one. Ask:
- Do you have a PRD already, or should we create one together?
- What's the repo path?
- What's the test command? (e.g.,
bundle exec rake,npm test) - How many iterations max? (default: 25)
PRD Format
# PRD
Branch: `<branch-name>`
## Stories
### US-001: <Story title>
- [ ] <Acceptance criterion>
- [ ] <Acceptance criterion>
### US-002: <Story title>
- [ ] <Acceptance criterion>Guidelines for stories:
- Small: Must fit in one context window
- Explicit criteria: Avoid vague ("Users can log in"), prefer specific checks
- Story order = priority (first = highest)
Note: Ralph is typically run in a git worktree. If already on the correct branch (or detached HEAD), the branch checkout is skipped.
Step 2: Start the Loop
~/.claude/skills/ralphing/assets/ralph.sh start <repo_path> <prd.md> [max_iterations] [test_cmd]This returns a session directory (e.g., /tmp/ralph/ABC123-...) and runs the loop in the background.
Step 3: Monitor Progress
Poll the session status periodically:
~/.claude/skills/ralphing/assets/ralph.sh status <ralph_dir>This outputs:
status:running,complete, orfailediteration: current/max iterations- Full contents of
progress.txt
Keep polling until status is complete or failed.
How the Loop Works
startcopies PRD, generates prompt, checks out branch (if needed), and spawns background process- Background loop: agent implements story -> commits -> runs tests
- If tests fail, reverts commit and retries (progress.txt preserved)
- Exits when agent signals
<promise>COMPLETE</promise>or max iterations reached - Parent agent polls
statusto observe progress without blocking
Resources
assets/ralph.sh- the loop script (start/status commands)assets/prompt.md- prompt template (uses<RALPH_DIR>placeholder)