ralph-cli

AI-driven PRD-to-implementation pipeline. Plan features with a relentless interview. Ship them autonomously with a live TUI.

ralph-cli owns the full feature lifecycle — plan → implement → review → learn — in a single tool. AI handles the content (discussion, decisions, code). The CLI handles the structure (file layout, process management, story selection, progress tracking). No more brittle prompts, misplaced files, or malformed JSON.

┌─ Ralph — projectname / order-management ───────────────┐
│                                                         │
│  US-001  Create orders schema           ✓ completed     │
│  US-002  Create orders repo             ✓ completed     │
│  US-003  Create orders service          ⏳ in progress  │
│  US-004  Create orders router           ○ pending       │
│  US-005  Add orders list page           ○ pending       │
│                                                         │
│  Iteration: 3/10    Elapsed: 12m 34s                    │
│                                                         │
│  ── Current log ──────────────────────────────────────  │
│  Running quality checks...                              │
│  Typecheck passed                                       │
│                                                         │
└─────────────────────────────────────────────────────────┘

Table of Contents

• Why ralph-cli?
• Requirements
• Installation
• Quickstart
• How It Works
• Commands
• Configuration
• File Structure
• Design Principles
• Platform Support

Why ralph-cli?

The traditional PRD-to-code workflow is fragmented:

• Feature planning happens in one chat.
• PRD writing happens in another.
• Implementation bounces between tools.
• Progress tracking is raw terminal logs.

ralph-cli collapses this into a single, opinionated pipeline:

| Stage | Who drives it | Output | | ---------------- | ------------------------------- | ------------------------------------ | | Init | Forge agent (codebase analysis) | AGENTS.md project spec | | Plan | cook interactive agent | prd.md with stories + criteria | | Prepare | CLI (deterministic) | prd.json, git branch, progress log | | Run | Muse (plan) → Forge (implement) | Code, commits, live TUI | | Review | Forge agent | review.md, gap stories | | Learn | Forge agent | Appended learnings in AGENTS.md |

The AI never chooses file paths, story IDs, commit messages, or commit timing. The CLI never makes content decisions. Clean separation, fewer bugs.

Requirements

• Node.js >= 18
• Forge CLI installed and available in PATH
• git (for branch and commit management)
• macOS (v1 targets macOS only; Linux/Windows are non-goals for v1)
• A project using git, ideally with existing quality-check scripts (typecheck, lint, test)

Installation

Install globally from npm:

# npm
npm install -g @lokecross/ralph-cli

# pnpm
pnpm add -g @lokecross/ralph-cli

# yarn
yarn global add @lokecross/ralph-cli

Verify the install:

ralph-cli --help

Quickstart

From the root of any git-tracked project:

1. Initialize

ralph-cli init

• Asks for a project code (e.g., projectname)
• Creates ralph-cli/config.json and ralph-cli/tasks/
• Installs the cook agent into .forge/agents/cook.md
• Spawns Forge to analyze your codebase and write AGENTS.md

2. Plan a feature

Open Forge and invoke the interactive planning agent:

forge
# then inside Forge:
:cook

The cook agent will:

• Ask for a feature name (kebab-case, e.g., order-management)
• Interview you one question at a time, proposing answers it found in your codebase
• Write ralph-cli/tasks/<feature>/prd.md with a story breakdown

3. Prepare the task

ralph-cli prepare --task order-management

• Extracts prd.json from the markdown (validated with Zod)
• Creates the ralph/<feature> git branch
• Initializes progress.txt

4. Run

ralph-cli run --task order-management

Watch the TUI as Muse plans and Forge implements each story, running your quality checks, committing, and updating the live progress board.

If only one task exists in ralph-cli/tasks/, --task can be omitted:

ralph-cli run

How It Works

The two-phase loop

For each story, ralph-cli runs a plan-then-implement pipeline:

1. Muse (planner) — claude-sonnet-4-6
   • Receives story details, codebase patterns, behavioral rules
   • Produces a plan file (saved to prompts/US-XXX-PLAN.md)
2. Forge (implementer) — claude-haiku-4-5
   • Inherits Muse's conversation ID → full planning context, no re-prompting
   • Implements the story, runs quality checks, updates prd.json, writes notes
3. ralph-cli (orchestrator)
   • Commits all changes with feat: <story title> (or wip: on failure)
   • Archives the plan, re-reads prd.json, picks the next story

Story selection

Each iteration picks the highest-priority story where:

• passes is false
• failures < max-failures (default 3)
• All dependsOn stories have passes: true

If dependencies fail, dependent stories are automatically blocked:

US-001  Create orders schema         ❌ failed (3 attempts)
US-002  Create orders repo           ⛔ blocked by US-001
US-003  Create orders service        ✓ completed
US-004  Create orders router         ⛔ blocked by US-001

Post-run phase

After the loop halts (all complete, max iterations, or all blocked):

1. Review — Forge compares the PRD against progress.txt + git diff --stat. If gaps are found, new stories are appended and the loop runs once more.
2. Learnings — Patterns discovered during the run are distilled into the ## Learnings section of AGENTS.md, available to every future agent invocation.
3. Pull Request — Changes are pushed and a PR is created via gh.

Commands

ralph-cli init

One-time project setup. Re-runnable to refresh AGENTS.md.

ralph-cli init

ralph-cli prepare

Extracts prd.json from prd.md and sets up the branch + progress log.

ralph-cli prepare --task <feature>
ralph-cli prepare --task <feature> --force    # re-extract prd.json

| Flag | Default | Description | | ----------- | -------------------- | ----------------------------------------- | | --task | auto if single task | Feature name to prepare | | --force | false | Re-extract prd.json even if it exists |

ralph-cli run

Runs the autonomous implementation loop with the live TUI.

ralph-cli run --task <feature>

| Flag | Default | Description | | -------------------- | -------------------- | ---------------------------------------------- | | --task | auto if single task | Feature name to run | | --max-iterations | 10 | Maximum loop iterations | | --max-failures | 3 | Max failures per story before skipping | | --skip-planning | false | Skip the Muse planning phase | | --skip-review | false | Skip the post-run review phase |

Ctrl+C kills the current iteration and stops the loop cleanly. No daemons, no PID files.

:cook (Forge agent)

Interactive feature planner, invoked inside Forge, not as a CLI command:

forge
:cook

Installed automatically by ralph-cli init at .forge/agents/cook.md.

Configuration

ralph-cli/config.json is created by init. All fields except agent and project have sensible defaults.

{
  "agent": "forge",
  "project": "projectname",
  "planBeforeStory": true,
  "reviewAfterRun": true,
  "models": {
    "init": "claude-opus-4-6",
    "extract": "claude-sonnet-4-6",
    "muse": "claude-sonnet-4-6",
    "forge": "claude-haiku-4-5",
    "review": "claude-opus-4-6",
    "learnings": "claude-sonnet-4-6"
  }
}

Field reference

| Field | Type | Default | Purpose | | ------------------- | --------- | ------- | ---------------------------------------------------- | | agent | "forge" | — | Agent CLI to invoke | | project | string | — | Project code (e.g., projectname) | | planBeforeStory | boolean | true | Run Muse planning before each Forge implementation | | reviewAfterRun | boolean | true | Run post-run review (may append gap stories) | | models.init | string | opus | Model for init codebase analysis | | models.extract | string | sonnet | Model for prepare JSON extraction | | models.muse | string | sonnet | Model for the planning phase | | models.forge | string | haiku | Model for the implementation phase | | models.review | string | opus | Model for post-run review | | models.learnings | string | sonnet | Model for learnings distillation |

The entire models object (and any individual key) may be omitted — defaults are applied automatically.

Flag vs config override semantics

CLI flags can force-disable planBeforeStory and reviewAfterRun, but cannot force-enable them when the config has them off. This is intentional — the config is always the authoritative ceiling.

File Structure

Everything under ralph-cli/ is committed to git. It's project documentation.

<project>/
├── AGENTS.md                      # Project spec + accumulated learnings (auto-loaded by Forge)
├── .forge/
│   └── agents/
│       └── cook.md                # Feature-planning agent
└── ralph-cli/
    ├── config.json
    └── tasks/
        └── order-management/
            ├── prd.md             # Human-readable PRD (source of truth)
            ├── prd.json           # Machine-generated from prd.md
            ├── progress.txt       # Patterns + per-story log
            ├── review.md          # Post-run review
            └── prompts/
                ├── US-001-muse.md
                ├── US-001-PLAN.md
                ├── US-002-muse.md
                └── US-002-PLAN.md

Design Principles

1. AI does content, code does structure. Agents never decide file paths, story IDs, priorities, or commit messages. The CLI never makes content decisions.
2. prd.md is the source of truth. The human-readable PRD is the contract. prd.json is derived at runtime, validated by Zod.
3. CLI orchestrates, agents interact. ralph-cli picks stories, manages the branch, runs the loop. Interactive sessions are Forge agents.
4. AGENTS.md auto-loads. No prompt injection of project spec or learnings — Forge loads AGENTS.md on every invocation.
5. Explicit story dependencies. dependsOn is declared in the PRD. Failures cascade. The run halts when no eligible stories remain.
6. Single review pass. One post-run review, one gap-filling pass. No infinite loops.
7. Process lifecycle = CLI lifecycle. No daemons. Ctrl+C stops everything.
8. Everything is committed. PRDs, progress logs, reviews, learnings, prompts — all version-controlled.

Platform Support

• v1 targets macOS. File watching (fs.watch) and TUI behaviour are validated on macOS only.
• Linux / Windows are non-goals for v1 but may work with minor caveats.

Non-goals (v1)

• Web dashboard
• macOS notifications
• Mid-flight PRD editing / hot-reloading stories
• Multi-project management in a single CLI session
• Remote monitoring
• Multiple agent CLI support (Forge-only for now)

Links

• npm: @lokecross/ralph-cli
• Forge CLI: https://forgecode.dev

Built for fast, deterministic, AI-driven feature delivery.