ralphctl

A CLI tool for managing Ralph Loop workflows—autonomous development sessions driven by Claude.

Installation

Install as a binary compiled from source:

cargo install --git https://github.com/wcygan/ralphctl

Prerequisites

Requires the claude CLI to be installed and available in PATH. You must be authenticated with Claude.

Quickstart

These 3 self-contained commands get you started:

ralphctl init
ralphctl interview
ralphctl run

They will setup the necessary structure, create context in the correct format, and run the loop.

Workflow

init → interview → run → verify → archive (or clean)

1. ralphctl init — Scaffold ralph loop files from templates
2. ralphctl interview — AI-guided interview to create SPEC.md and IMPLEMENTATION_PLAN.md
3. ralphctl run — Execute the autonomous development loop
4. Verify — Manually review the completed work
5. ralphctl archive — Save spec/plan to .ralphctl/archive/ and reset for next loop
6. ralphctl clean — Remove ralph loop files when done

Quick Start

# 1. Initialize a new ralph loop
ralphctl init

# 2. Interview to define your project (interactive)
ralphctl interview

# 3. Run the autonomous development loop
ralphctl run

# 4. Check progress at any time
ralphctl status

# 5a. Archive completed work and start fresh
ralphctl archive

# 5b. Or clean up when completely done
ralphctl clean

Commands

ralphctl init

Scaffold ralph loop files from templates.

ralphctl init [--force]

Flag	Description
--force	Overwrite existing files without prompting

Creates SPEC.md, IMPLEMENTATION_PLAN.md, and PROMPT.md in the current directory. Templates are fetched from GitHub and cached locally for offline use.

ralphctl interview

Interactive AI-guided interview to create project spec and implementation plan.

ralphctl interview [--model <MODEL>]

Flag	Description
--model	Claude model to use (default: sonnet)

Launches an interactive Claude session that asks questions about your project and generates a detailed SPEC.md and IMPLEMENTATION_PLAN.md.

ralphctl run

Execute the ralph loop until done or blocked.

ralphctl run [--max-iterations N] [--pause] [--model <MODEL>]

Flag	Description
--max-iterations	Maximum iterations before stopping (default: 50)
--pause	Prompt for confirmation before each iteration
--model	Claude model to use (default: sonnet)

The loop reads PROMPT.md and pipes it to claude -p, streaming output in real-time. Each iteration is logged to ralph.log.

Exit codes:

• 0 — Completed ([[RALPH:DONE]] detected)
• 1 — General error
• 2 — Max iterations reached
• 3 — Blocked ([[RALPH:BLOCKED]] detected)
• 130 — Interrupted (Ctrl+C)

ralphctl status

Show ralph loop progress.

ralphctl status

Parses IMPLEMENTATION_PLAN.md and displays a progress bar:

[████████░░░░] 60% (12/20 tasks)

ralphctl archive

Save spec and plan to timestamped archive, reset for next loop.

ralphctl archive [--force]

Flag	Description
--force	Skip confirmation prompt

Archives SPEC.md and IMPLEMENTATION_PLAN.md to .ralphctl/archive/<timestamp>/, then replaces them with blank templates.

ralphctl clean

Remove ralph loop files.

ralphctl clean [--force]

Flag	Description
--force	Skip confirmation prompt

Removes SPEC.md, IMPLEMENTATION_PLAN.md, PROMPT.md, and ralph.log.

ralphctl update

Install the latest version of ralphctl from GitHub.

ralphctl update

Runs cargo install --git https://github.com/wcygan/ralphctl to fetch and compile the latest release.

ralphctl fetch-latest-prompt

Fetch the latest PROMPT.md from GitHub without affecting other files.

ralphctl fetch-latest-prompt

Downloads the latest orchestration prompt from GitHub, preserving your SPEC.md and IMPLEMENTATION_PLAN.md. Use this when ralphctl is updated with new control signals or improved prompting logic.

ralphctl reverse

Investigate a codebase to answer a question—diagnosing bugs, understanding legacy code, or mapping dependencies before refactoring.

ralphctl reverse [OPTIONS] [QUESTION]

Argument/Flag	Description
QUESTION	The investigation question (reads from QUESTION.md if omitted)
--max-iterations	Maximum iterations before stopping (default: 100)
--pause	Prompt for confirmation before each iteration
--model	Claude model to use (e.g., 'sonnet', 'opus')

Examples:

# Investigate with a question directly
ralphctl reverse "Why does the authentication flow fail for OAuth users?"

# Use existing QUESTION.md
ralphctl reverse

# With options
ralphctl reverse --model opus "How does the payment processing work?"
ralphctl reverse --pause --max-iterations 50 "Why is the cache invalidation slow?"

Exit codes:

• 0 — Found (question answered, FINDINGS.md written)
• 1 — General error
• 2 — Max iterations reached
• 3 — Blocked ([[RALPH:BLOCKED]] detected)
• 4 — Inconclusive (could not determine answer, FINDINGS.md written)
• 130 — Interrupted (Ctrl+C)

Unlike run which builds software by completing tasks, reverse operates read-only and produces investigation reports. See Reverse Mode for details.

How It Works

The Ralph Loop is an autonomous development workflow:

1. ralphctl init creates SPEC.md, IMPLEMENTATION_PLAN.md, and PROMPT.md
2. ralphctl interview guides you through defining your project specification and task list
3. ralphctl run pipes the prompt to claude -p and streams output
4. Claude reads the spec, finds the next unchecked task, implements it, and marks it complete
5. Loop repeats with fresh context each iteration (avoiding context rot)
6. Loop exits when Claude outputs [[RALPH:DONE]] or [[RALPH:BLOCKED:<reason>]]

Why Fresh Context?

Each iteration starts with clean context. This eliminates "context rot"—the degradation of AI performance as conversation history accumulates with stale information and abandoned approaches. Local files (SPEC.md, IMPLEMENTATION_PLAN.md) serve as persistent memory across iterations.

Magic Strings

The loop detects these signals in Claude's output:

• [[RALPH:CONTINUE]] — Task completed, more tasks remain; loop continues automatically
• [[RALPH:DONE]] — All tasks complete, exit successfully
• [[RALPH:BLOCKED:<reason>]] — Cannot proceed, requires human intervention

Reverse Mode

Reverse Mode enables autonomous investigation workflows. While Forward Mode (ralphctl run) builds software by completing tasks, Reverse Mode (ralphctl reverse) analyzes codebases to answer questions.

When to Use Reverse Mode

• Diagnosing bugs: "Why does the cache fail under high load?"
• Understanding legacy code: "How does the authentication system work?"
• Pre-refactoring analysis: "What are all the dependencies on this module?"
• Architecture exploration: "How does data flow through the system?"

Reverse Mode Workflow

# Start an investigation
ralphctl reverse "Why does the payment processing fail intermittently?"

# Claude investigates autonomously, updating INVESTIGATION.md
# When done, produces FINDINGS.md with the answer

# Archive the investigation and start fresh
ralphctl archive

Reverse Mode Files

File	Purpose
QUESTION.md	The investigation question
INVESTIGATION.md	Running log of hypotheses with checkboxes
FINDINGS.md	Final synthesized report
REVERSE_PROMPT.md	Instructions for investigation loop

Reverse Mode Signals

• [[RALPH:CONTINUE]] — Still investigating, more hypotheses to explore
• [[RALPH:FOUND:<summary>]] — Question answered, FINDINGS.md written
• [[RALPH:INCONCLUSIVE:<why>]] — Cannot determine answer, FINDINGS.md written
• [[RALPH:BLOCKED:<reason>]] — Cannot proceed, requires human intervention

Example Investigation

$ ralphctl reverse "Why does the auth token expire prematurely?"

=== Iteration 1 starting ===
[Claude explores token generation code...]

=== Iteration 2 starting ===
[Claude examines token validation logic...]

=== Iteration 3 starting ===
[Claude finds the issue and writes FINDINGS.md]

Investigation complete: Token lifetime calculation uses seconds instead of milliseconds

Ralph Loop Files

Forward Mode (run)

File	Purpose
SPEC.md	Project specification and requirements
IMPLEMENTATION_PLAN.md	Task list with checkboxes
PROMPT.md	Orchestration prompt piped to Claude
ralph.log	Iteration output log

Reverse Mode (reverse)

File	Purpose
QUESTION.md	The investigation question
INVESTIGATION.md	Running log of hypotheses with checkboxes
FINDINGS.md	Final synthesized report
REVERSE_PROMPT.md	Instructions for investigation loop

Shared

File	Purpose
ralph.log	Iteration output log (both modes)
.ralphctl/archive/	Archived specs, plans, and investigations

License

MIT