ralph-orchestrator
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
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
Markdown
[](/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
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
- {
- "name": "ralph-orchestrator",
- "owner": {
- "name": "mikeyobrien"
- },
- "metadata": {
- "description": "Public agent skills for operating and introspecting Ralph",
- "version": "1.2.0"
- },
- "plugins": [
- {
- "name": "ralph-orchestrator",
- "description": "Skills for creating hats, operating loops, and introspecting Ralph via its published llms.txt",
- "source": "./",
- "strict": false,
- "skills": [
- "./skills/ralph-hats",
- "./skills/ralph-loop",
- "./skills/ralph-docs"
- ]
- }
- ]
- }
README.md · README · 291 lines
- <!-- 2026-01-28 -->
- # Ralph Orchestrator
- [](LICENSE)
- [](https://www.rust-lang.org/)
- [](https://github.com/mikeyobrien/ralph-orchestrator/actions)
- [](CONTRIBUTING.md#coverage)
- [](https://github.com/hesreallyhim/awesome-claude-code)
- [](https://github.com/varun1505/awesome-software-factories)
- [](https://mikeyobrien.github.io/ralph-orchestrator/)
- [](https://discord.gg/XWUyeUNffh)
- A hat-based orchestration framework that keeps AI agents in a loop until the task is done.
- > "Me fail English? That's unpossible!" - Ralph Wiggum
- **[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/)**
- ## Installation
- ### Via npm (Recommended)
- ```bash
- npm install -g @ralph-orchestrator/ralph-cli
- ```
- ### Via GitHub Releases installer
- ```bash
- curl --proto '=https' --tlsv1.2 -LsSf \
- https://github.com/mikeyobrien/ralph-orchestrator/releases/latest/download/ralph-cli-installer.sh | sh
- ```
- ### Via Cargo
- ```bash
- cargo install ralph-cli
- ```
- > Homebrew is not currently published from this repository's automated release flow. Prefer npm, Cargo, or the GitHub Releases installer.
- ## Quick Start
- ```bash
- # 1. Initialize Ralph with your preferred backend
- ralph init --backend claude
- # 2. Plan your feature (interactive PDD session)
- ralph plan "Add user authentication with JWT"
- # Creates: .ralph/specs/user-authentication/requirements.md, design.md, implementation-plan.md
- # 3. Implement the feature
- ralph run -p "Implement the feature in .ralph/specs/user-authentication/"
- ```
- Ralph iterates until it outputs `LOOP_COMPLETE` or hits the iteration limit.
- For simpler tasks, skip planning and run directly:
- ```bash
- ralph run -p "Add input validation to the /users endpoint"
- ```
- ## Web Dashboard (Alpha)
- > **Alpha:** The web dashboard is under active development. Expect rough edges and breaking changes.
- <img width="1513" height="1128" alt="image" src="https://github.com/user-attachments/assets/ce5f072f-3d81-44d8-8f2f-88b42b33a3be" />
- Ralph includes a web dashboard for monitoring and managing orchestration loops.
- ```bash
- ralph web # starts Rust RPC API + frontend + opens browser
- ralph web --no-open # skip browser auto-open
- ralph web --backend-port 4000 # custom RPC API port
- ralph web --frontend-port 8080 # custom frontend port
- ralph web --legacy-node-api # opt into deprecated Node tRPC backend
- ```
- ### MCP Server Workspace Scope
- `ralph mcp serve` is scoped to a single workspace root per server instance.
- ```bash
- ralph mcp serve --workspace-root /path/to/repo
- ```
- Precedence is:
- 1. `--workspace-root`
- 2. `RALPH_API_WORKSPACE_ROOT`
- 3. current working directory
- For multi-repo use, run one MCP server instance per repo/workspace. Ralph's current
- control-plane APIs persist config, tasks, loops, planning sessions, and collections
- under a single workspace root, so server-per-workspace is the deterministic model.
- **Requirements:**
- - Rust toolchain (for `ralph-api`)
- - Node.js >= 18 + npm (for the frontend)
- On first run, `ralph web` auto-detects missing `node_modules` and runs `npm install`.
- To set up Node.js:
- ```bash
- # Option 1: nvm (recommended)
- nvm install # reads .nvmrc
- # Option 2: direct install
- # https://nodejs.org/
- ```
- For development:
- ```bash
- npm install # install frontend + legacy backend deps
- npm run dev:api # Rust RPC API (port 3000)
- npm run dev:web # frontend (port 5173)
- npm run dev # frontend only (default)
- npm run dev:legacy-server # deprecated Node backend (optional)
- npm run test # all frontend/backend workspace tests
- ```
- ## MCP Server Mode
- Ralph can run as an MCP server over stdio for MCP-compatible clients:
- ```bash
- ralph mcp serve
- ```
- Use this mode from an MCP client configuration rather than an interactive terminal workflow.
- ## What is Ralph?
- Ralph implements the [Ralph Wiggum technique](https://ghuntley.com/ralph/) — autonomous task completion through continuous iteration. It supports:
- - **Multi-Backend Support** — Claude Code, Kiro, Gemini CLI, Codex, Forge, Amp, Copilot CLI, OpenCode, Pi, Roo, OMP
- - **Hat System** — Specialized personas coordinating through events
- - **Backpressure** — Gates that reject incomplete work (tests, lint, typecheck)
- - **Memories & Tasks** — Persistent learning and runtime work tracking
- - **5 Supported Builtins** — `code-assist`, `debug`, `research`, `review`, and `pdd-to-code-assist`, with more patterns documented as examples
- ## RObot (Human-in-the-Loop)
- Ralph supports human interaction during orchestration via Telegram. Agents can ask questions and block until answered; humans can send proactive guidance at any time.
- Quick onboarding (Telegram):
- ```bash
- ralph bot onboard --telegram # guided setup (token + chat id)
- ralph bot status # verify config
- ralph bot test # send a test message
- ralph run -c ralph.bot.yml -p "Help the human"
- ```
- ```yaml
- # ralph.yml
- RObot:
- enabled: true
- telegram:
- bot_token: "your-token" # Or RALPH_TELEGRAM_BOT_TOKEN env var
- ```
- - **Agent questions** — Agents emit `human.interact` events; the loop blocks until a response arrives or times out
- - **Proactive guidance** — Send messages anytime to steer the agent mid-loop
- - **Parallel loop routing** — Messages route via reply-to, `@loop-id` prefix, or default to primary
- - **Telegram commands** — `/status`, `/tasks`, `/restart` for real-time loop visibility
- See the [Telegram guide](https://mikeyobrien.github.io/ralph-orchestrator/guide/telegram/) for setup instructions.
- ## Documentation
- Full documentation is available at **[mikeyobrien.github.io/ralph-orchestrator](https://mikeyobrien.github.io/ralph-orchestrator/)**:
- - [Installation](https://mikeyobrien.github.io/ralph-orchestrator/getting-started/installation/)
- - [Quick Start](https://mikeyobrien.github.io/ralph-orchestrator/getting-started/quick-start/)
- - [Configuration](https://mikeyobrien.github.io/ralph-orchestrator/guide/configuration/)
- - [CLI Reference](https://mikeyobrien.github.io/ralph-orchestrator/guide/cli-reference/)
- - [Presets](https://mikeyobrien.github.io/ralph-orchestrator/guide/presets/)
- - [Concepts: Hats & Events](https://mikeyobrien.github.io/ralph-orchestrator/concepts/hats-and-events/)
- - [Architecture](https://mikeyobrien.github.io/ralph-orchestrator/advanced/architecture/)
- ## FAQ
- ### General
- **What is Ralph Orchestrator?**
- 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.
- **How is Ralph different from other AI coding tools?**
- 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.
- ### Installation & Setup
- **What are the system requirements?**
- - Rust 1.75+ (for the `ralph-api` component)
- - Node.js >= 18 + npm (for the web dashboard frontend)
- - An AI coding assistant CLI (Claude Code, Codex, Gemini CLI, etc.)
- **Which installation method should I use?**
- - **npm** (recommended for most users): `npm install -g @ralph-orchestrator/ralph-cli`
- - **Cargo**: `cargo install ralph-cli` (best for Rust developers)
- - **GitHub Releases installer**: One-link install with `curl ... | sh`
- **Is Homebrew supported?**
- Homebrew is not currently published from this repository's automated release flow. Prefer npm, Cargo, or the GitHub Releases installer.
- ### Usage
- **How do I start a new project with Ralph?**
- ```bash
- ralph init --backend claude
- ralph plan "Add user authentication with JWT"
- ralph run -p "Implement the feature in .ralph/specs/user-authentication/"
- ```
- **What backends does Ralph support?**
- Claude Code, Kiro, Gemini CLI, Codex, Forge, Amp, Copilot CLI, OpenCode, Pi, Roo, and OMP (oh-my-pi).
- **What is the "hat system"?**
- 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.
- ### RObot (Human-in-the-Loop)
- **What is RObot?**
- RObot enables human interaction during orchestration via Telegram. Agents can ask questions and block until answered; humans can send proactive guidance mid-loop.
- **How do I set up Telegram integration?**
- ```bash
- ralph bot onboard --telegram # guided setup
- ralph bot status # verify config
- ralph bot test # send a test message
- ```
- ### Web Dashboard
- **How do I access the web dashboard?**
- 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.
- **Can I customize the dashboard ports?**
- Yes: `ralph web --backend-port 4000 --frontend-port 8080`
- ### MCP Server
- **How do I run Ralph as an MCP server?**
- ```bash
- ralph mcp serve --workspace-root /path/to/repo
- ```
- Each MCP server instance is scoped to a single workspace root. For multi-repo use, run one instance per workspace.
- ### Troubleshooting
- **Ralph fails to start with "node_modules not found"**
- Run `npm install` in the project directory, or let `ralph web` auto-detect and install on first run.
- **How do I set up Node.js if not installed?**
- Use nvm (recommended): `nvm install` (reads `.nvmrc`), or install directly from https://nodejs.org/
- **Where can I get help?**
- - Join our [Discord server](https://discord.gg/XWUyeUNffh)
- - Report bugs on the [Issue Tracker](https://github.com/mikeyobrien/ralph-orchestrator/issues)
- - Read full documentation at [mikeyobrien.github.io/ralph-orchestrator](https://mikeyobrien.github.io/ralph-orchestrator/)
- ## Contributing
- Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.
- ## License
- MIT License — See [LICENSE](LICENSE) for details.
- ## 💬 Community & Support
- Join the **ralph-orchestrator** community to discuss AI agent patterns, get help with your implementation, or contribute to the roadmap.
- * **Discord**: [Join our server](https://discord.gg/XWUyeUNffh) to chat with the maintainers and other users in real-time.
- * **GitHub Issues**: For bug reports and formal feature requests, please use the [Issue Tracker](https://github.com/mikeyobrien/ralph-orchestrator/issues).
- ## Acknowledgments
- - **[Geoffrey Huntley](https://ghuntley.com/ralph/)** — Creator of the Ralph Wiggum technique
- - **[“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
- - **[Strands Agents SOP](https://github.com/strands-agents/agent-sop)** — Agent SOP framework
- - **[ratatui](https://ratatui.rs/)** — Terminal UI framework
- ---
- *"I'm learnding!" - Ralph Wiggum*
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.