ralphing

This skill should be used when setting up or running the Ralph autonomous coding loop that iterates through stories, runs tests, commits, and logs learnings.

⭐36stars🔀1forks📁View on GitHub🕐Updated Jan 8, 2026⬇️2downloads

When & Why to Use This Skill

Ralphing is an advanced Claude skill designed for autonomous software development and feature implementation. It orchestrates a sophisticated AI coding loop that processes Product Requirement Documents (PRDs), iterates through user stories, executes automated tests, and commits code independently. By utilizing persistent memory through git history and background execution, it enables the seamless delivery of complex, multi-step features with minimal human intervention, effectively acting as an autonomous pair programmer.

Use Cases

  • Autonomous Feature Engineering: Automatically transform a structured PRD into a series of functional, tested, and committed code changes by iterating through defined user stories.
  • Background Development Loops: Initiate long-running coding tasks that operate in the background, allowing developers to focus on high-level architecture while the agent handles the implementation and testing cycle.
  • Self-Healing Implementation: Utilize the autonomous 'implement-test-fix' cycle to ensure that all generated code passes specified test commands (e.g., npm test, rake) before moving to the next story.
  • Multi-Iteration Project Progress: Manage complex software updates that require persistent memory and state tracking across multiple context windows and git worktrees.
nameralphing
descriptionThis skill should be used when setting up or running the Ralph autonomous coding loop that iterates through stories, runs tests, commits, and logs learnings.

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:

  1. Do you have a PRD already, or should we create one together?
  2. What's the repo path?
  3. What's the test command? (e.g., bundle exec rake, npm test)
  4. 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, or failed
  • iteration: current/max iterations
  • Full contents of progress.txt

Keep polling until status is complete or failed.

How the Loop Works

  1. start copies PRD, generates prompt, checks out branch (if needed), and spawns background process
  2. Background loop: agent implements story -> commits -> runs tests
  3. If tests fail, reverts commit and retries (progress.txt preserved)
  4. Exits when agent signals <promise>COMPLETE</promise> or max iterations reached
  5. Parent agent polls status to observe progress without blocking

Resources

  • assets/ralph.sh - the loop script (start/status commands)
  • assets/prompt.md - prompt template (uses <RALPH_DIR> placeholder)