https://github.com/wcygan/ralphctl
Ralph Loop Controller
https://github.com/wcygan/ralphctl
claude-code llm-orchestration ralph ralph-loop ralph-wiggum
Last synced: 18 days ago
JSON representation
Ralph Loop Controller
- Host: GitHub
- URL: https://github.com/wcygan/ralphctl
- Owner: wcygan
- Created: 2026-01-27T03:39:57.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-01-27T17:24:26.000Z (5 months ago)
- Last Synced: 2026-01-27T17:28:01.710Z (5 months ago)
- Topics: claude-code, llm-orchestration, ralph, ralph-loop, ralph-wiggum
- Language: Rust
- Homepage:
- Size: 227 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# ralphctl
A CLI tool for managing Ralph Loop workflows—autonomous development sessions driven by Claude.
## Installation
Install as a binary compiled from source:
```bash
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:
```bash
ralphctl init
ralphctl interview
ralphctl run
```
They will setup the necessary structure, create context in the correct format, and [run the loop](https://github.com/wcygan/ralphctl/blob/368a650db9ab6c9385cec19ac94074744f0669ec/src/main.rs#L372).
## 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
```bash
# 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.
```bash
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.
```bash
ralphctl interview [--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.
```bash
ralphctl run [--max-iterations N] [--pause] [--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.
```bash
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.
```bash
ralphctl archive [--force]
```
| Flag | Description |
|------|-------------|
| `--force` | Skip confirmation prompt |
Archives SPEC.md and IMPLEMENTATION_PLAN.md to `.ralphctl/archive//`, then replaces them with blank templates.
### `ralphctl clean`
Remove ralph loop files.
```bash
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.
```bash
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.
```bash
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.
```bash
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:**
```bash
# 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](#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:]]`
### 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:]]` — 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
```bash
# 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:]]` — Question answered, FINDINGS.md written
- `[[RALPH:INCONCLUSIVE:]]` — Cannot determine answer, FINDINGS.md written
- `[[RALPH:BLOCKED:]]` — Cannot proceed, requires human intervention
### Example Investigation
```bash
$ 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