ralph-cc

ralph-cc orchestrates multi-feature software work through an interactive Claude Code session. It takes a one-page PRD, decomposes it into a dependency graph of small tasks, runs independent tasks in parallel inside isolated git worktrees using Claude Code subagents, verifies each one, and merges them back with a smoke-test gate.

Why not claude -p?

claude -p (headless/API mode) is metered per token. ralph-cc runs entirely through one interactive Claude Code session — /ralph-run is the orchestrator, and it dispatches ralph-worker subagents via the Task tool. This stays on the subscription/interactive usage pool, not the metered headless path.

What ralph-cc is (not a compiled program)

ralph-cc is a set of Claude Code customizations plus one small Python scheduler:

Component	Type	Purpose
/ralph-plan	slash command	Read a PRD, write tasks.json
/ralph-run	slash command	Orchestrate parallel worker subagents
/ralph-status	slash command	Show task progress
/ralph-graph	slash command	Render the dependency graph with parallel lanes
ralph-worker	subagent	Execute one task in its worktree
ralph-sched	Python CLI	Deterministic scheduler (stdlib only)
ralph-graph	Python CLI	ASCII dependency-graph renderer (stdlib only)
ralph-tasks-schema.json	JSON Schema	Validate tasks.json

System-wide, install-once

Commands install to ~/.claude/commands/, the agent to ~/.claude/agents/, and the ralph-sched / ralph-graph CLIs to ~/.local/bin/. Nothing goes into project repos — per-run artifacts (.ralph-worktrees/, .ralph-logs/, .ralph-smoke/) are added to .git/info/exclude by /ralph-run so they never appear in git status.

Install

macOS / Linux:

bash install.sh

Windows (PowerShell):

# If needed: Unblock-File install.ps1
powershell -ExecutionPolicy Bypass -File install.ps1

Windows (double-click / cmd.exe):

install.cmd

All three installers are idempotent — re-running always overwrites with the latest version.

Usage

# 1. In a git repo with at least one commit, write a PRD.md
/ralph-plan PRD.md

# 2. Review the generated tasks.json
/ralph-status
/ralph-graph          # renders the dependency graph with parallel lanes
/ralph-graph --all    # include already-done tasks

# 3. Run — parallel workers execute in isolated worktrees
/ralph-run

# With options:
/ralph-run --max-parallel 3 --model opus --restart-every 10 --rollback-on-smoke-fail

Resuming after a checkpoint or interruption: Progress is durable in .ralph-logs/state.json. Just run /ralph-run again in a fresh session — it picks up where it stopped.

Options for /ralph-run

Flag	Default	Description
--max-parallel N	from tasks.json (5)	Max tasks per batch
--model opus|sonnet	per-task setting	Override all workers
--no-smoke	off	Skip smoke tests
--restart-every N	5	Checkpoint every N batches; 0 disables
--rollback-on-smoke-fail	off	git reset --hard if smoke fails

Components map

PRD.md ──/ralph-plan──► tasks.json
                             │
             /ralph-run (interactive, orchestrator)
                   │
                   ├─ ralph-sched next ──► next file-disjoint batch
                   ├─ git worktree add  ──► .ralph-worktrees/<id>/
                   ├─ Task(ralph-worker) × N  (parallel)
                   ├─ independent verify (exit code = truth)
                   ├─ merge passed tasks → $BASE
                   ├─ smoke test in .ralph-smoke/
                   └─ ralph-sched done/fail ──► .ralph-logs/state.json

Optional: single binary

ralph-sched and ralph-graph can each be reimplemented as a compiled binary of the same name (any language) with no caller changes — the tools are invoked by name only, and the language is an implementation detail.

Requirements

• Claude Code (interactive session)
• Python 3 (for ralph-sched and ralph-graph)
• Git

ralph-cc