Keeps an AI coding agent working in a loop, checking its output against tests and lint, until a task is actually finished. It also helps turn rough ideas into design documents and code task files, and it reviews pull requests.
Auto-invoked ships a router so the right skill fires automatically as you prompt. No remembering which skill to call.
Normal is the plain upstream plugin, installed as-is. You invoke its skills yourself.
Claude Code
The plugin> /plugin marketplace add mikeyobrien/ralph-orchestrator> /plugin install ralph-orchestrator@ralph-orchestratorAuto-invocation> /plugin marketplace add flowy-sh/flowy-core> /plugin install flowy-core> /plugin install flowy-ralph-orchestrator
Codex
$ npx skills add mikeyobrien/ralph-orchestrator -a codex
Cursor
$ npx skills add mikeyobrien/ralph-orchestrator -a cursor
Gemini CLI
$ npx skills add mikeyobrien/ralph-orchestrator -a gemini-cli
GitHub Copilot
$ copilot plugin marketplace add mikeyobrien/ralph-orchestrator$ copilot plugin install ralph-orchestrator@ralph-orchestrator
OpenCode
$ npx skills add mikeyobrien/ralph-orchestrator -a opencode
Windsurf
$ npx skills add mikeyobrien/ralph-orchestrator -a windsurf
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 | Getting Started | Presets
npm install -g @ralph-orchestrator/ralph-cli
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/mikeyobrien/ralph-orchestrator/releases/latest/download/ralph-cli-installer.sh | sh
cargo install ralph-cli
Homebrew is not currently published from this repository's automated release flow. Prefer npm, Cargo, or the GitHub Releases installer.
# 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:
ralph run -p "Add input validation to the /users endpoint"
Alpha: The web dashboard is under active development. Expect rough edges and breaking changes.
Ralph includes a web dashboard for monitoring and managing orchestration loops.
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
ralph mcp serve is scoped to a single workspace root per server instance.
ralph mcp serve --workspace-root /path/to/repo
Precedence is:
--workspace-rootRALPH_API_WORKSPACE_ROOTFor 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:
ralph-api)On first run, ralph web auto-detects missing node_modules and runs npm install.
To set up Node.js:
# Option 1: nvm (recommended)
nvm install # reads .nvmrc
# Option 2: direct install
# https://nodejs.org/
For development:
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
Ralph can run as an MCP server over stdio for MCP-compatible clients:
ralph mcp serve
Use this mode from an MCP client configuration rather than an interactive terminal workflow.
Ralph implements the Ralph Wiggum technique — autonomous task completion through continuous iteration. It supports:
code-assist, debug, research, review, and pdd-to-code-assist, with more patterns documented as examplesRalph 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):
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"
# ralph.yml
RObot:
enabled: true
telegram:
bot_token: "your-token" # Or RALPH_TELEGRAM_BOT_TOKEN env var
human.interact events; the loop blocks until a response arrives or times out@loop-id prefix, or default to primary/status, /tasks, /restart for real-time loop visibilitySee the Telegram guide for setup instructions.
Full documentation is available at mikeyobrien.github.io/ralph-orchestrator:
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.
What are the system requirements?
ralph-api component)Which installation method should I use?
npm install -g @ralph-orchestrator/ralph-clicargo install ralph-cli (best for Rust developers)curl ... | shIs Homebrew supported? Homebrew is not currently published from this repository's automated release flow. Prefer npm, Cargo, or the GitHub Releases installer.
How do I start a new project with Ralph?
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.
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?
ralph bot onboard --telegram # guided setup
ralph bot status # verify config
ralph bot test # send a test message
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
How do I run Ralph as an MCP server?
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.
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?
Contributions are welcome! See CONTRIBUTING.md for guidelines and CODE_OF_CONDUCT.md for community standards.
MIT License — See LICENSE for details.
Join the ralph-orchestrator community to discuss AI agent patterns, get help with your implementation, or contribute to the roadmap.
"I'm learnding!" - Ralph Wiggum
Stars on GitHub
View @mikeyobrien’s profileGives Claude access to device features such as the clipboard, contacts, call log, location, dialogs, and device controls like vibration and battery status. Adds skills for haptic feedback, flashlight, and quick status checks on a phone.
@mikeyobrienSee 12 ralph-orchestrator alternatives
Skills for the OpenClaw personal AI assistant, covering browser automation, routing requests to coding agents, presenting canvas widgets, running apps on temporary machines, and sharing diffs.
@steipeteGives Claude Code users skills to drive Orca-managed worktrees, terminals and the embedded browser through the orca CLI, plus Jira and Linear ticket work and inline HTML chat visuals. Covers chart, table and mockup output.
@stablyaiOrchestrates teams of AI agents to run work like a company, with a Node.js server and React UI. Adds skills for delegating tasks, following up on results, reviewing team status, and managing Paperclip tasks from Hermes.
@paperclipaiOrganizes your AI agents for round-the-clock operation, with tools to hire, schedule and report on your agent team. Lets you oversee the agents without staying online yourself.
@lobehubInstall it once and the right skill fires as you prompt, with no slash command to remember. It is listed on Flowy in the Agent Orchestration category. It includes code-assist, code-task-generator, evaluate-presets. Free and open source.
Is this plugin yours?
Claim it with GitHubSubmit a pluginPromote it