Ralph Orchestrator

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

Installation

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.

Quick Start

# 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"

Web Dashboard (Alpha)

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

MCP Server Workspace Scope

ralph mcp serve is scoped to a single workspace root per server instance.

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:

# 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

MCP Server Mode

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.

What is Ralph?

Ralph implements the Ralph Wiggum technique — 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):

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

• 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 for setup instructions.

Documentation

Full documentation is available at mikeyobrien.github.io/ralph-orchestrator:

• Installation
• Quick Start
• Configuration
• CLI Reference
• Presets
• Concepts: Hats & Events
• 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?

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?

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?

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
• Report bugs on the Issue Tracker
• Read full documentation at mikeyobrien.github.io/ralph-orchestrator

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines and CODE_OF_CONDUCT.md for community standards.

License

MIT License — See 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 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.

Acknowledgments

• Geoffrey Huntley — Creator of the Ralph Wiggum technique
• Strands Agents SOP — Agent SOP framework
• ratatui — Terminal UI framework

---

"I'm learnding!" - Ralph Wiggum