ralph-cli

Ralph — Autonomous PRD-Driven Agent Loop

Ralph is a file-based agent loop that breaks work into stories defined in a prd.json file and executes them one at a time using AI coding agents (OpenCode, Claude Code, Codex, etc.).

Installation

npm install -g superacli
sc plugins install ralph-cli

Core Concepts

PRD (Product Requirements Document)

A JSON file containing a project name, description, and an ordered list of user stories:

{
  "name": "My Feature",
  "branchName": "ralph/my-feature",
  "description": "What this PRD is about",
  "userStories": [
    {
      "id": "US-001",
      "title": "Add database schema",
      "description": "As a developer, I need...",
      "acceptanceCriteria": ["Column x exists", "Migration runs"],
      "priority": 1,
      "passes": false,
      "dependsOn": []
    }
  ]
}

Stories

Each story must be completable in one agent iteration. Stories have:

• ID: Sequential (US-001, US-002, etc.)
• Priority: Lower number = higher priority
• dependsOn: Story IDs that must complete first
• acceptanceCriteria: Verifiable checks the agent must satisfy
• passes: false until completed, then true

Dependencies

Stories execute in dependency order:

• Schema/database -> Backend logic -> UI components -> Integration
• A story is "blocked" until all its dependsOn stories pass
• Ralph always selects the highest-priority unblocked story

Agent Workflow

1. Create a PRD

sc ralph-cli init run "Feature Name" --prd ./tasks/prd.json

2. Check Status

sc ralph-cli status run --prd ./tasks/prd.json

3. Run the Agent Loop

# Default timeout: 30 minutes
sc ralph-cli run run --prd ./tasks/prd.json

# Custom timeout (e.g., 10 minutes for quick tasks, 60 min for complex)
sc ralph-cli run run --prd ./tasks/prd.json --timeout 600
sc ralph-cli run run --prd ./tasks/prd.json --timeout 3600

4. Preview Prompts (Dry Run)

sc ralph-cli run run --prd ./tasks/prd.json --dry-run
sc ralph-cli prompt run --prd ./tasks/prd.json --story US-001

5. Story Lifecycle

1. Ralph selects the next available story
2. Generates a prompt with story details + acceptance criteria + prerequisites
3. Spawns the agent CLI (openmode, claude, codex, etc.) with the prompt
4. Agent implements the story
5. Ralph marks passes: true in prd.json
6. Ralph commits changes via git
7. Repeat until all stories pass

PRD Best Practices

• One story = one agent iteration: If a story is too big, split it
• Acceptance criteria must be verifiable: Not vague like "works well"
• Order by dependencies: Lower-priority stories that depend on earlier ones
• Include quality gates: Typecheck, lint, test commands in acceptance criteria
• Use ralph/ branch prefix: E.g., ralph/kotlin-migration

Agent Guidance

No-Timeout Mode

For long-running or complex agent tasks (e.g., large refactors, migrations), pass --no-timeout to disable the per-story timeout entirely. The agent runs until it finishes or is manually interrupted.

sc ralph-cli run run --prd ./prd.json --no-timeout

Note: --no-timeout overrides any --timeout value. Use with caution — an unresponsive agent may run indefinitely.

Timeout Management

Ralph defaults to a 30-minute timeout per story (--timeout 1800). Adjust based on story complexity:

• Quick fixes / simple edits: --timeout 120 (2 min)
• Single-file changes: --timeout 300 (5 min)
• Multi-file features (default): --timeout 1800 (30 min)
• Complex refactors / migrations: --timeout 3600 (60 min)
• Indeterminate tasks: --no-timeout (disable timeout)

When invoking ralph-cli via supercli from another agent, always pass an appropriate --timeout to prevent premature termination:

sc ralph-cli run run --prd ./prd.json --timeout 1800

If a story times out, split it into smaller stories or increase the timeout. If the agent needs indeterminate time (e.g., a complex refactor), use --no-timeout to disable the timeout entirely. Ralph retries timed-out stories the next time you run the loop.

Commands via supercli

Command	Description
sc ralph-cli run run --prd <file>	Execute the agent loop (default timeout: 30 min)
sc ralph-cli run run --prd <file> --timeout <sec>	Run with custom agent timeout
sc ralph-cli run run --prd <file> --no-timeout	Run with no timeout (agent runs until done)
sc ralph-cli status run --prd <file>	Show progress
sc ralph-cli story next --prd <file>	Show next available story
sc ralph-cli prompt run --prd <file>	Print agent prompt for next story
sc ralph-cli init run <name> --prd <file>	Scaffold a new PRD
sc ralph-cli --help	Passthrough to ralph-cli CLI