{"id":50179438,"url":"https://github.com/wcygan/ralphctl","last_synced_at":"2026-05-25T06:34:34.034Z","repository":{"id":334840939,"uuid":"1142976387","full_name":"wcygan/ralphctl","owner":"wcygan","description":"Ralph Loop Controller","archived":false,"fork":false,"pushed_at":"2026-01-27T17:24:26.000Z","size":232,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-27T17:28:01.710Z","etag":null,"topics":["claude-code","llm-orchestration","ralph","ralph-loop","ralph-wiggum"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wcygan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-27T03:39:57.000Z","updated_at":"2026-01-27T17:24:30.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/wcygan/ralphctl","commit_stats":null,"previous_names":["wcygan/ralphctl"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/wcygan/ralphctl","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wcygan%2Fralphctl","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wcygan%2Fralphctl/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wcygan%2Fralphctl/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wcygan%2Fralphctl/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wcygan","download_url":"https://codeload.github.com/wcygan/ralphctl/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wcygan%2Fralphctl/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33462851,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-25T06:32:55.349Z","status":"ssl_error","status_checked_at":"2026-05-25T06:32:35.322Z","response_time":57,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","llm-orchestration","ralph","ralph-loop","ralph-wiggum"],"created_at":"2026-05-25T06:34:32.607Z","updated_at":"2026-05-25T06:34:34.029Z","avatar_url":"https://github.com/wcygan.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ralphctl\n\nA CLI tool for managing Ralph Loop workflows—autonomous development sessions driven by Claude.\n\n## Installation\n\nInstall as a binary compiled from source:\n\n```bash\ncargo install --git https://github.com/wcygan/ralphctl\n```\n\n### Prerequisites\n\nRequires the `claude` CLI to be installed and available in PATH. You must be authenticated with Claude.\n\n## Quickstart\n\nThese 3 self-contained commands get you started:\n\n```bash\nralphctl init\nralphctl interview\nralphctl run\n```\n\nThey 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).\n\n## Workflow\n\n```\ninit → interview → run → verify → archive (or clean)\n```\n\n1. **`ralphctl init`** — Scaffold ralph loop files from templates\n2. **`ralphctl interview`** — AI-guided interview to create SPEC.md and IMPLEMENTATION_PLAN.md\n3. **`ralphctl run`** — Execute the autonomous development loop\n4. **Verify** — Manually review the completed work\n5. **`ralphctl archive`** — Save spec/plan to `.ralphctl/archive/` and reset for next loop\n6. **`ralphctl clean`** — Remove ralph loop files when done\n\n## Quick Start\n\n```bash\n# 1. Initialize a new ralph loop\nralphctl init\n\n# 2. Interview to define your project (interactive)\nralphctl interview\n\n# 3. Run the autonomous development loop\nralphctl run\n\n# 4. Check progress at any time\nralphctl status\n\n# 5a. Archive completed work and start fresh\nralphctl archive\n\n# 5b. Or clean up when completely done\nralphctl clean\n```\n\n## Commands\n\n### `ralphctl init`\n\nScaffold ralph loop files from templates.\n\n```bash\nralphctl init [--force]\n```\n\n| Flag | Description |\n|------|-------------|\n| `--force` | Overwrite existing files without prompting |\n\nCreates `SPEC.md`, `IMPLEMENTATION_PLAN.md`, and `PROMPT.md` in the current directory. Templates are fetched from GitHub and cached locally for offline use.\n\n### `ralphctl interview`\n\nInteractive AI-guided interview to create project spec and implementation plan.\n\n```bash\nralphctl interview [--model \u003cMODEL\u003e]\n```\n\n| Flag | Description |\n|------|-------------|\n| `--model` | Claude model to use (default: sonnet) |\n\nLaunches an interactive Claude session that asks questions about your project and generates a detailed SPEC.md and IMPLEMENTATION_PLAN.md.\n\n### `ralphctl run`\n\nExecute the ralph loop until done or blocked.\n\n```bash\nralphctl run [--max-iterations N] [--pause] [--model \u003cMODEL\u003e]\n```\n\n| Flag | Description |\n|------|-------------|\n| `--max-iterations` | Maximum iterations before stopping (default: 50) |\n| `--pause` | Prompt for confirmation before each iteration |\n| `--model` | Claude model to use (default: sonnet) |\n\nThe loop reads PROMPT.md and pipes it to `claude -p`, streaming output in real-time. Each iteration is logged to `ralph.log`.\n\n**Exit codes:**\n- `0` — Completed (`[[RALPH:DONE]]` detected)\n- `1` — General error\n- `2` — Max iterations reached\n- `3` — Blocked (`[[RALPH:BLOCKED]]` detected)\n- `130` — Interrupted (Ctrl+C)\n\n### `ralphctl status`\n\nShow ralph loop progress.\n\n```bash\nralphctl status\n```\n\nParses IMPLEMENTATION_PLAN.md and displays a progress bar:\n\n```\n[████████░░░░] 60% (12/20 tasks)\n```\n\n### `ralphctl archive`\n\nSave spec and plan to timestamped archive, reset for next loop.\n\n```bash\nralphctl archive [--force]\n```\n\n| Flag | Description |\n|------|-------------|\n| `--force` | Skip confirmation prompt |\n\nArchives SPEC.md and IMPLEMENTATION_PLAN.md to `.ralphctl/archive/\u003ctimestamp\u003e/`, then replaces them with blank templates.\n\n### `ralphctl clean`\n\nRemove ralph loop files.\n\n```bash\nralphctl clean [--force]\n```\n\n| Flag | Description |\n|------|-------------|\n| `--force` | Skip confirmation prompt |\n\nRemoves SPEC.md, IMPLEMENTATION_PLAN.md, PROMPT.md, and ralph.log.\n\n### `ralphctl update`\n\nInstall the latest version of ralphctl from GitHub.\n\n```bash\nralphctl update\n```\n\nRuns `cargo install --git https://github.com/wcygan/ralphctl` to fetch and compile the latest release.\n\n### `ralphctl fetch-latest-prompt`\n\nFetch the latest PROMPT.md from GitHub without affecting other files.\n\n```bash\nralphctl fetch-latest-prompt\n```\n\nDownloads 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.\n\n### `ralphctl reverse`\n\nInvestigate a codebase to answer a question—diagnosing bugs, understanding legacy code, or mapping dependencies before refactoring.\n\n```bash\nralphctl reverse [OPTIONS] [QUESTION]\n```\n\n| Argument/Flag | Description |\n|---------------|-------------|\n| `QUESTION` | The investigation question (reads from QUESTION.md if omitted) |\n| `--max-iterations` | Maximum iterations before stopping (default: 100) |\n| `--pause` | Prompt for confirmation before each iteration |\n| `--model` | Claude model to use (e.g., 'sonnet', 'opus') |\n\n**Examples:**\n\n```bash\n# Investigate with a question directly\nralphctl reverse \"Why does the authentication flow fail for OAuth users?\"\n\n# Use existing QUESTION.md\nralphctl reverse\n\n# With options\nralphctl reverse --model opus \"How does the payment processing work?\"\nralphctl reverse --pause --max-iterations 50 \"Why is the cache invalidation slow?\"\n```\n\n**Exit codes:**\n- `0` — Found (question answered, FINDINGS.md written)\n- `1` — General error\n- `2` — Max iterations reached\n- `3` — Blocked (`[[RALPH:BLOCKED]]` detected)\n- `4` — Inconclusive (could not determine answer, FINDINGS.md written)\n- `130` — Interrupted (Ctrl+C)\n\nUnlike `run` which builds software by completing tasks, `reverse` operates read-only and produces investigation reports. See [Reverse Mode](#reverse-mode) for details.\n\n## How It Works\n\nThe Ralph Loop is an autonomous development workflow:\n\n1. `ralphctl init` creates `SPEC.md`, `IMPLEMENTATION_PLAN.md`, and `PROMPT.md`\n2. `ralphctl interview` guides you through defining your project specification and task list\n3. `ralphctl run` pipes the prompt to `claude -p` and streams output\n4. Claude reads the spec, finds the next unchecked task, implements it, and marks it complete\n5. Loop repeats with fresh context each iteration (avoiding context rot)\n6. Loop exits when Claude outputs `[[RALPH:DONE]]` or `[[RALPH:BLOCKED:\u003creason\u003e]]`\n\n### Why Fresh Context?\n\nEach 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.\n\n### Magic Strings\n\nThe loop detects these signals in Claude's output:\n\n- `[[RALPH:CONTINUE]]` — Task completed, more tasks remain; loop continues automatically\n- `[[RALPH:DONE]]` — All tasks complete, exit successfully\n- `[[RALPH:BLOCKED:\u003creason\u003e]]` — Cannot proceed, requires human intervention\n\n## Reverse Mode\n\nReverse Mode enables autonomous investigation workflows. While Forward Mode (`ralphctl run`) builds software by completing tasks, Reverse Mode (`ralphctl reverse`) analyzes codebases to answer questions.\n\n### When to Use Reverse Mode\n\n- **Diagnosing bugs**: \"Why does the cache fail under high load?\"\n- **Understanding legacy code**: \"How does the authentication system work?\"\n- **Pre-refactoring analysis**: \"What are all the dependencies on this module?\"\n- **Architecture exploration**: \"How does data flow through the system?\"\n\n### Reverse Mode Workflow\n\n```bash\n# Start an investigation\nralphctl reverse \"Why does the payment processing fail intermittently?\"\n\n# Claude investigates autonomously, updating INVESTIGATION.md\n# When done, produces FINDINGS.md with the answer\n\n# Archive the investigation and start fresh\nralphctl archive\n```\n\n### Reverse Mode Files\n\n| File | Purpose |\n|------|---------|\n| `QUESTION.md` | The investigation question |\n| `INVESTIGATION.md` | Running log of hypotheses with checkboxes |\n| `FINDINGS.md` | Final synthesized report |\n| `REVERSE_PROMPT.md` | Instructions for investigation loop |\n\n### Reverse Mode Signals\n\n- `[[RALPH:CONTINUE]]` — Still investigating, more hypotheses to explore\n- `[[RALPH:FOUND:\u003csummary\u003e]]` — Question answered, FINDINGS.md written\n- `[[RALPH:INCONCLUSIVE:\u003cwhy\u003e]]` — Cannot determine answer, FINDINGS.md written\n- `[[RALPH:BLOCKED:\u003creason\u003e]]` — Cannot proceed, requires human intervention\n\n### Example Investigation\n\n```bash\n$ ralphctl reverse \"Why does the auth token expire prematurely?\"\n\n=== Iteration 1 starting ===\n[Claude explores token generation code...]\n\n=== Iteration 2 starting ===\n[Claude examines token validation logic...]\n\n=== Iteration 3 starting ===\n[Claude finds the issue and writes FINDINGS.md]\n\nInvestigation complete: Token lifetime calculation uses seconds instead of milliseconds\n```\n\n## Ralph Loop Files\n\n### Forward Mode (run)\n\n| File | Purpose |\n|------|---------|\n| `SPEC.md` | Project specification and requirements |\n| `IMPLEMENTATION_PLAN.md` | Task list with checkboxes |\n| `PROMPT.md` | Orchestration prompt piped to Claude |\n| `ralph.log` | Iteration output log |\n\n### Reverse Mode (reverse)\n\n| File | Purpose |\n|------|---------|\n| `QUESTION.md` | The investigation question |\n| `INVESTIGATION.md` | Running log of hypotheses with checkboxes |\n| `FINDINGS.md` | Final synthesized report |\n| `REVERSE_PROMPT.md` | Instructions for investigation loop |\n\n### Shared\n\n| File | Purpose |\n|------|---------|\n| `ralph.log` | Iteration output log (both modes) |\n| `.ralphctl/archive/` | Archived specs, plans, and investigations |\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwcygan%2Fralphctl","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwcygan%2Fralphctl","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwcygan%2Fralphctl/lists"}