start using Ralph with npx ralph-scaffold

You might have heard about RALPH,
I publishedralph-scaffold npx script which can provide you with all files needed to start using ralph, simply run

npx ralph-scaffold

and you are good to go.
(I use setup from Ryan Carson)
https://x.com/ryancarson/status/2008548371712135632
What is Ralph?

its a workflow, simple idea, to loop the code agent over and over, until it reach the goal, each time it make mistake it will learn from it. each time it make progress it will take note.

Every loop, will restart code agent starting with fresh context window, supply it with notes on things it learned so far, and progresses
This eliminate the weakness of "Context Drift",

However,
this can dramatically increase token usage, and if it drifts, its gonna snowball through entire iterations, potentially wasting tokens.

Ralph works well on

• Small Task Stories
• Good feedack on interations , like typecheck or linters,
• Explicit criteria

Matt Pocock explained this really well
https://www.youtube.com/watch?v=_IK18goX4X8

Since the token usages could potentially out of control, you may want to try it with claude premium plans, and avoid API based token (i tried it, the token usage is nuts)

---

How It Works

A bash loop that:
Pipes a prompt into your AI agent
Agent picks the next story from prd.json
Agent implements it
Agent runs typecheck + tests
Agent commits if passing
Agent marks story done
Agent logs learnings
Loop repeats until done

Memory persists only through:

Git commits
progress.txt (learnings)
prd.json (task status)

scripts/ralph/
├── ralph.sh
├── prompt.md
├── prd.json
└── progress.txt

ralph.sh

The loop:

#!/bin/bash
set -e

MAX_ITERATIONS=${1:-10}
SCRIPT_DIR="$(cd "$(dirname \
  "${BASH_SOURCE[0]}")" && pwd)"

echo "🚀 Starting Ralph"

for i in $(seq 1 $MAX_ITERATIONS); do
  echo "═══ Iteration $i ═══"

  OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" \
    | claude --dangerously-skip-permissions 2>&1 \
    | tee /dev/stderr) || true

  if echo "$OUTPUT" | \
    grep -q "<promise>COMPLETE</promise>"
  then
    echo "✅ Done!"
    exit 0
  fi

  sleep 2
done

echo "⚠️ Max iterations reached"
exit 1

Make executable:

chmod +x scripts/ralph/ralph.sh

prompt.md

Instructions for each iteration:

# Ralph Agent Instructions

## Your Task

1. Read `scripts/ralph/prd.json`
2. Read `scripts/ralph/progress.txt`
   (check Codebase Patterns first)
3. Check you're on the correct branch
4. Pick highest priority story 
   where `passes: false`
5. Implement that ONE story
6. Run typecheck and tests
7. Update AGENTS.md files with learnings
8. Commit: `feat: [ID] - [Title]`
9. Update prd.json: `passes: true`
10. Append learnings to progress.txt

## Progress Format

APPEND to progress.txt:

## [Date] - [Story ID]
- What was implemented
- Files changed
- **Learnings:**
  - Patterns discovered
  - Gotchas encountered
---

## Codebase Patterns

Add reusable patterns to the TOP 
of progress.txt:

## Codebase Patterns
- Migrations: Use IF NOT EXISTS
- React: useRef<Timeout | null>(null)

## Stop Condition

If ALL stories pass, reply:
<promise>COMPLETE</promise>

Otherwise end normally.

prd.json

Your task list:

{
  "branchName": "ralph/feature",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add login form",
      "acceptanceCriteria": [
        "Email/password fields",
        "Validates email format",
        "typecheck passes"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Key fields:
branchName — branch to use
priority — lower = first
passes — set true when done

progress.txt

Start with context:

# Ralph Progress Log
Started: 2024-01-15

## Codebase Patterns
- Migrations: IF NOT EXISTS
- Types: Export from actions.ts

## Key Files
- db/schema.ts
- app/auth/actions.ts
---

Ralph appends after each story.
Patterns accumulate across iterations.

Running Ralph

run the ralph script with 25 iterations

./scripts/ralph/ralph.sh 25

Ralph will:

• Create the feature branch
• Complete stories one by one
• Commit after each
• Stop when all pass