Skip to content
Back to search

ralph-orchestrator

SkillGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 13 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/mikeyobrien/ralph-orchestrator with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/mikeyobrien/ralph-orchestrator'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mikeyobrien--ralph-orchestrator/badge.svg)](/listings/mikeyobrien--ralph-orchestrator)

HTML

<a href="/listings/mikeyobrien--ralph-orchestrator"><img src="/api/listings/mikeyobrien--ralph-orchestrator/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Via npm (Recommended)

npm install -g @ralph-orchestrator/ralph-cli

Via GitHub Releases installer

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/mikeyobrien/ralph-orchestrator/releases/latest/download/ralph-cli-installer.sh | sh

Via Cargo

cargo install ralph-cli

> Homebrew is not currently published from this repository's automated release flow. Prefer npm, Cargo, or the GitHub Releases installer.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 23 lines
  1. {
  2. "name": "ralph-orchestrator",
  3. "owner": {
  4. "name": "mikeyobrien"
  5. },
  6. "metadata": {
  7. "description": "Public agent skills for operating and introspecting Ralph",
  8. "version": "1.2.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "ralph-orchestrator",
  13. "description": "Skills for creating hats, operating loops, and introspecting Ralph via its published llms.txt",
  14. "source": "./",
  15. "strict": false,
  16. "skills": [
  17. "./skills/ralph-hats",
  18. "./skills/ralph-loop",
  19. "./skills/ralph-docs"
  20. ]
  21. }
  22. ]
  23. }
README.md · README · 291 lines
  1. <!-- 2026-01-28 -->
  2. # Ralph Orchestrator
  3. [![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
  4. [![Rust](https://img.shields.io/badge/rust-1.75+-orange)](https://www.rust-lang.org/)
  5. [![Build](https://img.shields.io/github/actions/workflow/status/mikeyobrien/ralph-orchestrator/ci.yml?branch=main&label=CI)](https://github.com/mikeyobrien/ralph-orchestrator/actions)
  6. [![Coverage](https://img.shields.io/endpoint?url=https://mikeyobrien.github.io/ralph-orchestrator/badges/coverage.json)](CONTRIBUTING.md#coverage)
  7. [![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge.svg)](https://github.com/hesreallyhim/awesome-claude-code)
  8. [![Mentioned in Awesome Software Factories](https://awesome.re/mentioned-badge.svg)](https://github.com/varun1505/awesome-software-factories)
  9. [![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://mikeyobrien.github.io/ralph-orchestrator/)
  10. [![Discord](https://img.shields.io/discord/1482421188700667906?label=Discord&logo=discord&logoColor=white)](https://discord.gg/XWUyeUNffh)
  11. A hat-based orchestration framework that keeps AI agents in a loop until the task is done.
  12. > "Me fail English? That's unpossible!" - Ralph Wiggum
  13. **[Documentation](https://mikeyobrien.github.io/ralph-orchestrator/)** | **[Getting Started](https://mikeyobrien.github.io/ralph-orchestrator/getting-started/quick-start/)** | **[Presets](https://mikeyobrien.github.io/ralph-orchestrator/guide/presets/)**
  14. ## Installation
  15. ### Via npm (Recommended)
  16. ```bash
  17. npm install -g @ralph-orchestrator/ralph-cli
  18. ```
  19. ### Via GitHub Releases installer
  20. ```bash
  21. curl --proto '=https' --tlsv1.2 -LsSf \
  22. https://github.com/mikeyobrien/ralph-orchestrator/releases/latest/download/ralph-cli-installer.sh | sh
  23. ```
  24. ### Via Cargo
  25. ```bash
  26. cargo install ralph-cli
  27. ```
  28. > Homebrew is not currently published from this repository's automated release flow. Prefer npm, Cargo, or the GitHub Releases installer.
  29. ## Quick Start
  30. ```bash
  31. # 1. Initialize Ralph with your preferred backend
  32. ralph init --backend claude
  33. # 2. Plan your feature (interactive PDD session)
  34. ralph plan "Add user authentication with JWT"
  35. # Creates: .ralph/specs/user-authentication/requirements.md, design.md, implementation-plan.md
  36. # 3. Implement the feature
  37. ralph run -p "Implement the feature in .ralph/specs/user-authentication/"
  38. ```
  39. Ralph iterates until it outputs `LOOP_COMPLETE` or hits the iteration limit.
  40. For simpler tasks, skip planning and run directly:
  41. ```bash
  42. ralph run -p "Add input validation to the /users endpoint"
  43. ```
  44. ## Web Dashboard (Alpha)
  45. > **Alpha:** The web dashboard is under active development. Expect rough edges and breaking changes.
  46. <img width="1513" height="1128" alt="image" src="https://github.com/user-attachments/assets/ce5f072f-3d81-44d8-8f2f-88b42b33a3be" />
  47. Ralph includes a web dashboard for monitoring and managing orchestration loops.
  48. ```bash
  49. ralph web # starts Rust RPC API + frontend + opens browser
  50. ralph web --no-open # skip browser auto-open
  51. ralph web --backend-port 4000 # custom RPC API port
  52. ralph web --frontend-port 8080 # custom frontend port
  53. ralph web --legacy-node-api # opt into deprecated Node tRPC backend
  54. ```
  55. ### MCP Server Workspace Scope
  56. `ralph mcp serve` is scoped to a single workspace root per server instance.
  57. ```bash
  58. ralph mcp serve --workspace-root /path/to/repo
  59. ```
  60. Precedence is:
  61. 1. `--workspace-root`
  62. 2. `RALPH_API_WORKSPACE_ROOT`
  63. 3. current working directory
  64. For multi-repo use, run one MCP server instance per repo/workspace. Ralph's current
  65. control-plane APIs persist config, tasks, loops, planning sessions, and collections
  66. under a single workspace root, so server-per-workspace is the deterministic model.
  67. **Requirements:**
  68. - Rust toolchain (for `ralph-api`)
  69. - Node.js >= 18 + npm (for the frontend)
  70. On first run, `ralph web` auto-detects missing `node_modules` and runs `npm install`.
  71. To set up Node.js:
  72. ```bash
  73. # Option 1: nvm (recommended)
  74. nvm install # reads .nvmrc
  75. # Option 2: direct install
  76. # https://nodejs.org/
  77. ```
  78. For development:
  79. ```bash
  80. npm install # install frontend + legacy backend deps
  81. npm run dev:api # Rust RPC API (port 3000)
  82. npm run dev:web # frontend (port 5173)
  83. npm run dev # frontend only (default)
  84. npm run dev:legacy-server # deprecated Node backend (optional)
  85. npm run test # all frontend/backend workspace tests
  86. ```
  87. ## MCP Server Mode
  88. Ralph can run as an MCP server over stdio for MCP-compatible clients:
  89. ```bash
  90. ralph mcp serve
  91. ```
  92. Use this mode from an MCP client configuration rather than an interactive terminal workflow.
  93. ## What is Ralph?
  94. Ralph implements the [Ralph Wiggum technique](https://ghuntley.com/ralph/) — autonomous task completion through continuous iteration. It supports:
  95. - **Multi-Backend Support** — Claude Code, Kiro, Gemini CLI, Codex, Forge, Amp, Copilot CLI, OpenCode, Pi, Roo, OMP
  96. - **Hat System** — Specialized personas coordinating through events
  97. - **Backpressure** — Gates that reject incomplete work (tests, lint, typecheck)
  98. - **Memories & Tasks** — Persistent learning and runtime work tracking
  99. - **5 Supported Builtins** — `code-assist`, `debug`, `research`, `review`, and `pdd-to-code-assist`, with more patterns documented as examples
  100. ## RObot (Human-in-the-Loop)
  101. Ralph supports human interaction during orchestration via Telegram. Agents can ask questions and block until answered; humans can send proactive guidance at any time.
  102. Quick onboarding (Telegram):
  103. ```bash
  104. ralph bot onboard --telegram # guided setup (token + chat id)
  105. ralph bot status # verify config
  106. ralph bot test # send a test message
  107. ralph run -c ralph.bot.yml -p "Help the human"
  108. ```
  109. ```yaml
  110. # ralph.yml
  111. RObot:
  112. enabled: true
  113. telegram:
  114. bot_token: "your-token" # Or RALPH_TELEGRAM_BOT_TOKEN env var
  115. ```
  116. - **Agent questions** — Agents emit `human.interact` events; the loop blocks until a response arrives or times out
  117. - **Proactive guidance** — Send messages anytime to steer the agent mid-loop
  118. - **Parallel loop routing** — Messages route via reply-to, `@loop-id` prefix, or default to primary
  119. - **Telegram commands** — `/status`, `/tasks`, `/restart` for real-time loop visibility
  120. See the [Telegram guide](https://mikeyobrien.github.io/ralph-orchestrator/guide/telegram/) for setup instructions.
  121. ## Documentation
  122. Full documentation is available at **[mikeyobrien.github.io/ralph-orchestrator](https://mikeyobrien.github.io/ralph-orchestrator/)**:
  123. - [Installation](https://mikeyobrien.github.io/ralph-orchestrator/getting-started/installation/)
  124. - [Quick Start](https://mikeyobrien.github.io/ralph-orchestrator/getting-started/quick-start/)
  125. - [Configuration](https://mikeyobrien.github.io/ralph-orchestrator/guide/configuration/)
  126. - [CLI Reference](https://mikeyobrien.github.io/ralph-orchestrator/guide/cli-reference/)
  127. - [Presets](https://mikeyobrien.github.io/ralph-orchestrator/guide/presets/)
  128. - [Concepts: Hats & Events](https://mikeyobrien.github.io/ralph-orchestrator/concepts/hats-and-events/)
  129. - [Architecture](https://mikeyobrien.github.io/ralph-orchestrator/advanced/architecture/)
  130. ## FAQ
  131. ### General
  132. **What is Ralph Orchestrator?**
  133. Ralph is a hat-based orchestration framework that implements the Ralph Wiggum technique — autonomous task completion through continuous iteration. It keeps AI agents in a loop until the task is done, supporting multiple backends like Claude Code, Gemini CLI, Codex, and more.
  134. **How is Ralph different from other AI coding tools?**
  135. Unlike single-shot AI assistants, Ralph iterates until completion using a "hat system" with specialized personas. It includes backpressure gates (tests, lint, typecheck) that reject incomplete work, plus persistent memories and tasks for continuous learning.
  136. ### Installation & Setup
  137. **What are the system requirements?**
  138. - Rust 1.75+ (for the `ralph-api` component)
  139. - Node.js >= 18 + npm (for the web dashboard frontend)
  140. - An AI coding assistant CLI (Claude Code, Codex, Gemini CLI, etc.)
  141. **Which installation method should I use?**
  142. - **npm** (recommended for most users): `npm install -g @ralph-orchestrator/ralph-cli`
  143. - **Cargo**: `cargo install ralph-cli` (best for Rust developers)
  144. - **GitHub Releases installer**: One-link install with `curl ... | sh`
  145. **Is Homebrew supported?**
  146. Homebrew is not currently published from this repository's automated release flow. Prefer npm, Cargo, or the GitHub Releases installer.
  147. ### Usage
  148. **How do I start a new project with Ralph?**
  149. ```bash
  150. ralph init --backend claude
  151. ralph plan "Add user authentication with JWT"
  152. ralph run -p "Implement the feature in .ralph/specs/user-authentication/"
  153. ```
  154. **What backends does Ralph support?**
  155. Claude Code, Kiro, Gemini CLI, Codex, Forge, Amp, Copilot CLI, OpenCode, Pi, Roo, and OMP (oh-my-pi).
  156. **What is the "hat system"?**
  157. Ralph uses specialized personas (hats) that coordinate through events. Each hat has a specific role — code-assist, debug, research, review, and pdd-to-code-assist — enabling structured multi-step task execution.
  158. ### RObot (Human-in-the-Loop)
  159. **What is RObot?**
  160. RObot enables human interaction during orchestration via Telegram. Agents can ask questions and block until answered; humans can send proactive guidance mid-loop.
  161. **How do I set up Telegram integration?**
  162. ```bash
  163. ralph bot onboard --telegram # guided setup
  164. ralph bot status # verify config
  165. ralph bot test # send a test message
  166. ```
  167. ### Web Dashboard
  168. **How do I access the web dashboard?**
  169. Run `ralph web` to start the Rust RPC API + frontend and open your browser. The dashboard is currently in Alpha — expect rough edges and breaking changes.
  170. **Can I customize the dashboard ports?**
  171. Yes: `ralph web --backend-port 4000 --frontend-port 8080`
  172. ### MCP Server
  173. **How do I run Ralph as an MCP server?**
  174. ```bash
  175. ralph mcp serve --workspace-root /path/to/repo
  176. ```
  177. Each MCP server instance is scoped to a single workspace root. For multi-repo use, run one instance per workspace.
  178. ### Troubleshooting
  179. **Ralph fails to start with "node_modules not found"**
  180. Run `npm install` in the project directory, or let `ralph web` auto-detect and install on first run.
  181. **How do I set up Node.js if not installed?**
  182. Use nvm (recommended): `nvm install` (reads `.nvmrc`), or install directly from https://nodejs.org/
  183. **Where can I get help?**
  184. - Join our [Discord server](https://discord.gg/XWUyeUNffh)
  185. - Report bugs on the [Issue Tracker](https://github.com/mikeyobrien/ralph-orchestrator/issues)
  186. - Read full documentation at [mikeyobrien.github.io/ralph-orchestrator](https://mikeyobrien.github.io/ralph-orchestrator/)
  187. ## Contributing
  188. Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.
  189. ## License
  190. MIT License — See [LICENSE](LICENSE) for details.
  191. ## 💬 Community & Support
  192. Join the **ralph-orchestrator** community to discuss AI agent patterns, get help with your implementation, or contribute to the roadmap.
  193. * **Discord**: [Join our server](https://discord.gg/XWUyeUNffh) to chat with the maintainers and other users in real-time.
  194. * **GitHub Issues**: For bug reports and formal feature requests, please use the [Issue Tracker](https://github.com/mikeyobrien/ralph-orchestrator/issues).
  195. ## Acknowledgments
  196. - **[Geoffrey Huntley](https://ghuntley.com/ralph/)** — Creator of the Ralph Wiggum technique
  197. - **[“You Don’t Need Long Context” (NVIDIA, arXiv 2611.05306)](https://arxiv.org/abs/2611.05306)** — Benchmarks the externalized-state/context-reset pattern at the core of Ralph’s loop: same accuracy, up to 8.8× lower inference cost
  198. - **[Strands Agents SOP](https://github.com/strands-agents/agent-sop)** — Agent SOP framework
  199. - **[ratatui](https://ratatui.rs/)** — Terminal UI framework
  200. ---
  201. *"I'm learnding!" - Ralph Wiggum*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.