ralph

Ralph

Autonomous AI development loop for Claude Code. Define user stories, run the loop, check back when it's done.

The concept comes from Geoffrey Huntley, who named it after Ralph Wiggum from The Simpsons. Each iteration spawns a fresh Claude instance with no memory of previous runs. The AI's work persists through files: git commits, a progress log, and a learnings file.

Available through the Ryde Ventures plugin marketplace.

Installation

Step 1: Install the plugin

# Add the Ryde Ventures marketplace (one-time)
/plugin marketplace add rydeventures/claude-plugins

# Install the plugin
/plugin install ralph@rydeventures-claude-plugins

Step 2: Install the bash script

The plugin includes a bash script that runs the autonomous loop. The installer creates a symlink to ralph in ~/.local/bin/.

Run the installer:

~/.claude/plugins/cache/rydeventures-claude-plugins/ralph/*/scripts/install.sh

If ~/.local/bin isn't in your PATH, add it:

echo 'export PATH="$PATH:$HOME/.local/bin"' >> ~/.zshrc
source ~/.zshrc

Updating

After updating the plugin in Claude Code, re-run the installer to update the symlinks. The ralph command will remind you if this is needed.

Manual Installation

Alternatively, copy the files manually from this repository. Note: manual installs use copies, not symlinks, so you'll need to re-copy after updates.

Bash script and prompt (required):

# Create directories
mkdir -p ~/.local/bin ~/.claude

# Copy files
cp scripts/ralph.sh ~/.local/bin/ralph
cp scripts/ralph-prompt.md ~/.claude/ralph-prompt.md

# Make executable
chmod +x ~/.local/bin/ralph

Skill (for /ralph command):

User-level (available in all projects):

mkdir -p ~/.claude/skills/ralph
cp skills/ralph/SKILL.md ~/.claude/skills/ralph/skill.md

Project-level (available only in this project):

mkdir -p .claude/skills/ralph
cp skills/ralph/SKILL.md .claude/skills/ralph/skill.md

Usage

1. Initialize a project

Open Claude Code in your project directory and run:

/ralph

Claude will ask about your feature and analyze the scope. For smaller tasks, it creates stories directly. For larger tasks, it offers to create a roadmap with phases.

.ralph/
├── stories.json    # Your user stories
├── progress.txt    # Implementation log per iteration
├── learnings.txt   # Patterns and gotchas (persists across runs)
└── roadmap.json    # (optional) Multi-phase project roadmap

2. Run the loop

Exit Claude Code and run from terminal:

ralph              # Runs until all stories complete
ralph 50           # Limit to 50 iterations
ralph 1            # Single iteration (useful for testing)
ralph update       # Refresh symlink after plugin update
ralph --version    # Show version
ralph --help       # Show help

Loopception

For larger projects, Ralph can go deeper. A loop within a loop: phases containing stories, each phase spawning its own Ralph loop until complete.

When /ralph detects a multi-phase task, it offers to create a roadmap:

/ralph "build a dashboard with auth, API, and frontend"

Claude: "This looks like it could be split into phases:
1. Authentication
2. API layer
3. Frontend dashboard

Should I create a roadmap with phases, or keep it as one set of stories?"

If you choose roadmap, it creates .ralph/roadmap.json:

{
  "project": "Dashboard",
  "phases": [
    {
      "id": 1,
      "title": "Authentication",
      "description": ["User model and migrations", "Login/logout endpoints"],
      "complete": false
    },
    {
      "id": 2,
      "title": "API Layer",
      "description": ["REST endpoints for CRUD", "Authentication middleware"],
      "complete": false
    },
    {
      "id": 3,
      "title": "Frontend",
      "description": ["Dashboard components", "Forms and validation"],
      "complete": false
    }
  ]
}

Then run:

ralph --roadmap                 # Runs all phases
ralph --roadmap --pause         # Pauses between phases for review

Each phase:

1. Sets up .ralph/ with stories for that phase
2. Runs iterations until all stories complete
3. Marks the phase complete: true in roadmap.json
4. Continues to next phase (or pauses if --pause)

3. Review results

When Ralph finishes (or hits max iterations), check:

• Git log for commits
• .ralph/progress.txt for what was implemented
• .ralph/learnings.txt for patterns discovered
• .ralph/stories.json for completion status

How it works