ralph

# Ralph GSD

> [!WARNING]
> **Claude Code Required** — This tool requires an active Claude Code subscription.
>
> **Cost Warning** — Running plans consumes Claude API usage. Autonomous loops can use significant quota.
>
> **Auto-Accept Mode** — Ralph runs Claude with `--dangerously-skip-permissions` enabled. It will make changes without confirmation prompts.
>
> **Recommendation** — Start with `ralph run` (single plan) to observe behavior before using `ralph run --loop`.

> Built on [Get Shit Done (GSD)](https://github.com/glittercowboy/get-shit-done) planning and inspired by the [original Ralph concept](https://ghuntley.com/ralph/) by Geoffrey Huntley.

Ralph executes your development plans automatically. You define what to build, Ralph breaks it into phases, creates detailed task plans, and executes them with verification. Each run preserves learnings in a `## Progress` section within the plan JSON file for the next run.

## Table of Contents
- [How It Works](#how-it-works)
- [Concept Hierarchy](#concept-hierarchy)
- [When to Use Ralph](#when-to-use-ralph)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Commands](#commands)
- [Configuration](#configuration)
- [Troubleshooting](#troubleshooting)

**Planning is mandatory** - Ralph enforces that you properly understand and plan work before executing.

## How It Works

Ralph uses a **phase-by-phase workflow**. You don't plan everything upfront - you work through one phase at a time:

```
┌───────────────────────────────────────────────────────────┐
│  ONE-TIME SETUP                                           │
│                                                           │
│  ralph init  →  ralph map  →  ralph roadmap               │
│                                                           │
└───────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────────────┐
│  PER-PHASE LOOP (repeat for each phase)                             │
│                                                                     │
│  ┌──────────┐   ┌──────────┐   ┌────────┐   ┌────────┐   ┌───────┐  │
│  │ discover │ → │ discuss  │ → │  plan  │ → │ review │ → │  run  │  │
│  │(optional)│   │(optional)│   │        │   │(recomm)│   │       │  │
│  └──────────┘   └──────────┘   └────────┘   └────────┘   └───────┘  │
│                                                                     │
│  Phase 1 → Phase 2 → Phase 3 → ... → Done                           │
│                                                                     │
│            ralph update ← (anytime you have new findings)           │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

         At any time: ralph status (see where you are)
```

## Concept Hierarchy

Ralph organizes work into a clear hierarchy. Here's how the structures nest:

```
Project (project.json)
├── Roadmap (roadmap.json)
│   ├── Phase 1 (integer)
│   │   ├── 01-01.json
│   │   ├── 01-01-summary.json
│   │   └── 01-02.json
│   ├── Phase 2 (integer)
│   │   └── 02-01.json
│   ├── Phase 2.1 (decimal - INSERTED)
│   │   └── 02.1-01.json
│   └── Phase 3 (integer)
│       └── ...
└── state.json
```

**Concepts:**
- **Project** - Top-level vision and requirements (project.json)
- **Roadmap** - Breakdown into phases (roadmap.json)
- **Phase** - Unit of work, integer (1, 2, 3) or decimal (5.1 for urgent insertions)
- **Plan** - Executable task bundle (NN-MM.json)
- **Task** - Individual unit of work (XML in plan files)
- **Summary** - Completion marker (NN-MM-summary.json)

**Phase numbering:** Integer phases (1, 2, 3) are planned work. Decimal phases (5.1, 5.2) are urgent insertions that execute between surrounding integers (e.g., 5 → 5.1 → 6).

## When to Use Ralph

**Good for:**
- Greenfield projects building from scratch
- Major refactors with clear phases
- Feature development with sequential steps
- Any work that can be broken into verifiable tasks

**Not for:**
- Quick one-off changes (use Claude directly)
- Exploratory work where scope is unclear
- Work requiring constant human judgment
- Debugging sessions or investigations

## Ralph vs GSD

| Component | Role |
|-----------|------|
| **GSD** | Planning brain - interactive workflows for project setup, roadmapping, and plan creation |
| **Ralph** | Execution engine - autonomous execution with verification, looping, and progress tracking |

Ralph wraps GSD commands in a simpler CLI (`ralph plan` calls `/gsd:plan-phase`, etc.) and adds:
- Verification after each task
- Autonomous looping across plans
- Progress tracking via `ralph status`
- Inactivity timeout protection

You can use GSD directly within Claude Code for interactive planning, or use Ralph for automated execution.

## Checking Progress: `ralph status`

Run `ralph status` anytime to see your current position:

```bash
$ ralph status

Ralph v2.0.0 - My Project

📦 Project Artifacts:
  ✓ project.json        Project vision and requirements
  ✓ roadmap.json        10 phases defined
  ✓ Codebase Maps       7 analysis documents
  ✓ state.json          Tracking execution
  ✓ Plans               3/10 phases have plans

Progress: [████░░░░░░░░░░░░░░░░] 20% (4/20 plans)

📍 Current Position:
  Phase: 2 of 10
  Plan:  01-02.json
  Status: Ready to execute

🎯 Suggested Next Actions:
  ralph run              Execute next incomplete plan
  ralph run --loop 5     Execute up to 5 plans autonomously
```

Use `ralph status -v` (verbose) to see all phases and their plans:

```bash
$ ralph status -v
...
Phases:
  ✓ Phase 1: Feature Verification (3/3)
      ✓ 01-01.json
      ✓ 01-02.json
      ✓ 01-03.json
  ◐ Phase 2: Mix World Media (1/2)
      ✓ 02-01.json
      ○ 02-02.json
  ○ Phase 3: Story Adaptation (0/0)
  ...
```

Use `ralph list` for a compact view of all phases and plans.

## Installation

### Prerequisites

1. **Claude Code CLI** - [Install Claude Code](https://claude.ai/code)
2. **GSD (Get Shit Done)** - Required for planning:
   ```bash
   npm install -g get-shit-done-cc
   ```

### Install Ralph

**Homebrew (recommended):**
```bash
brew tap daydemir/tap
brew install ralph
```

**From source:**
```bash
go install github.com/daydemir/ralph/cmd/ralph@latest
```

## Quick Start

```bash
# One-time setup
ralph init              # Create project.json
ralph map               # Analyze existing codebase (brownfield projects)
ralph roadmap           # Create roadmap.json with phases

# Per-phase cycle
ralph discover 1        # Research external APIs/docs (optional)
ralph discuss 1         # Align on scope and approach (optional)
ralph plan 1            # Create executable plan JSON files
ralph run               # Execute plans (or: ralph run --loop 5)
```

## Workflow Example

Here's a complete cycle for one phase:

```bash
# Phase 1: Authentication
ralph discover 1        # → Creates .planning/phases/01-auth/research.json
                        #   Researches OAuth providers, JWT libraries, etc.

ralph discuss 1         # → Creates .planning/phases/01-auth/context.json
                        #   Alignment conversation about scope, edge cases

ralph plan 1            # → Creates .planning/phases/01-auth/01-01.json, etc.
                        #   Breaks phase into executable task files

ralph run --loop        # Executes all plans for phase 1
                        # state.json updates automatically

# Phase 1 complete → now repeat for Phase 2
ralph discover 2
ralph discuss 2
ralph plan 2
ralph run --loop
```

## Pre-Planning: Discover vs Discuss

Before planning a phase, you can optionally run **discover** and/or **discuss** to build context:

| Command | Purpose | Output | When to Use |
|---------|---------|--------|-------------|
| `ralph discover N` | Research external docs, APIs, ecosystem options | `research.json` | Unfamiliar domain, new libraries, API integrat

[truncated…]