sensible-ralph

sensible-ralph

Autonomous overnight execution of Approved Linear issues — with review gates, worktree isolation, a DAG scope model, and Linear as the state machine.

A Claude Code plugin that extends the ralph technique (Geoff Huntley's original) with five properties the name is a nod to.

The five pillars

1. Safety — every session hands off to a review gate before anything merges. Worktree isolation keeps parallel sessions from stepping on each other. The DAG model won't dispatch two children of the same In-Review parent concurrently. Vanilla ralph ships straight to main.

2. Structure — three phases (spec → plan → impl) with three skills (/sr-spec, /sr-start, /sr-implement). A DAG scope model instead of a flat checklist. Linear's workflow states are the state machine — not a progress.txt blob. Vanilla ralph hands the loop a markdown file and walks away.

3. Traceability — every iteration ties to a Linear issue. Decisions, specs, progress logs, and dispatch records are durable artifacts in the filesystem and in Linear. Vanilla ralph remembers via a single mutable progress.txt.

4. Composability — skills are swappable. The orchestrator dispatches whichever implementation skill you point it at; the spec skill and orchestrator don't care what lives at the end of the pipe. Vanilla ralph is a fixed bash script.

5. Deliberation — idea → PRD → plan → code are separate phases. Thinking happens before the loop starts, so the autonomous implementer is executing a decided design, not figuring one out. Vanilla ralph hands the LLM a blob and lets it discover the scope as it goes.

Installation

This plugin ships as a self-marketplace (the repo is both marketplace and plugin). Inside Claude Code:

/plugin marketplace add seankao31/sensible-ralph
/plugin install sensible-ralph@sensible-ralph

At install time Claude Code will prompt for the plugin's userConfig values (workflow state names, label names, worktree base directory, model, log filename). All have sensible defaults; accepting them gets you a working setup.

Prerequisites

• Linear CLI (schpet/linear-cli) authenticated against your workspace (linear --version succeeds).

• jq on PATH.

• Three workspace-scoped Linear labels, one-time setup per workspace. Names are plugin-configurable; the defaults are ralph-failed, stale-parent, and ralph-coord-dep:

  linear label create --name ralph-failed --color '#EB5757' \
    --description 'Orchestrator dispatched this issue but it did not reach the review state.'
  linear label create --name stale-parent --color '#F2994A' \
    --description 'In-Review issue whose blocked-by parent was amended after dispatch.'
  linear label create --name ralph-coord-dep --color '#9B51E0' \
    --description 'Has at least one coord-dep blocked-by edge auto-added by the /sr-spec scan; cleared on /close-issue.'
  

• Per-repo .sensible-ralph.json at the repo root declaring which Linear projects this repo's sessions drain. Two shapes:

  // Explicit — one or more projects
  { "projects": ["Project A", "Project B"] }
  
  // Shorthand — Linear initiative, expanded to its member projects on every run
  { "initiative": "My Initiative Name" }
  

• .gitignore entries for the runtime artifacts the orchestrator writes to your repo root and worktrees:

  /.sensible-ralph/
  /.worktrees/
  ralph-output.log
  

  If you're upgrading from a version that wrote these artifacts at the repo root, run mkdir -p .sensible-ralph && mv progress.json ordered_queue.txt .sensible-ralph/ 2>/dev/null once at your consumer repo's root.

  (The paths match the plugin defaults. If you changed the worktree_base or stdout_log_filename userConfig values, substitute accordingly.)

Usage

End-to-end operator flow is in docs/usage.md. Subsystem design docs live in docs/design/; per-ticket implementation specs in docs/specs/; captured decisions in docs/decisions/.

Brief summary: