https://github.com/mikeyobrien/ralph-orchestrator
An improved implementation of the Ralph Wiggum technique for autonomous AI agent orchestration
https://github.com/mikeyobrien/ralph-orchestrator
ai ai-agents ai-agents-framework ai-developer-tools claude-code claude-code-cli codex-cli development-tools development-workflow gemini-cli kiro kiro-cli opencode ralph-loop ralph-wiggum
Last synced: 3 months ago
JSON representation
An improved implementation of the Ralph Wiggum technique for autonomous AI agent orchestration
- Host: GitHub
- URL: https://github.com/mikeyobrien/ralph-orchestrator
- Owner: mikeyobrien
- License: mit
- Created: 2025-09-07T18:17:13.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2026-02-21T15:03:32.000Z (4 months ago)
- Last Synced: 2026-02-21T21:00:37.423Z (4 months ago)
- Topics: ai, ai-agents, ai-agents-framework, ai-developer-tools, claude-code, claude-code-cli, codex-cli, development-tools, development-workflow, gemini-cli, kiro, kiro-cli, opencode, ralph-loop, ralph-wiggum
- Language: Rust
- Homepage:
- Size: 9.65 MB
- Stars: 1,875
- Watchers: 24
- Forks: 192
- Open Issues: 13
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome-agent-orchestrators - ralph-orchestrator - Hat-based orchestration that keeps agents in a loop until done. (Autonomous Loop Runners)
- awesome-claude-code - mikeyobrien/ralph-orchestrator - orchestrator?style=flat-square&logo=github) | Ralph Wiggum technique for autonomous AI agent orchestration | (Agent Orchestration)
- awesome-claude-code-and-skills - mikeyobrien/ralph-orchestrator - orchestrator?style=flat-square) (Multi-Agent Systems / Parallel Processing)
- awesome-openclaw-skills - ralph-orchestrator - | (Code & Developer Tools)
- awesome-ralph - mikeyobrien/ralph-orchestrator - Mikey O'Brien (Implementations)
- awesome-ralph - ralph-orchestrator - Rust orchestrator with 7 AI backends, Hat System for specialized personas, and interactive TUI mode. (Implementations / Standalone Implementations)
- awesome-cli-coding-agents - ralph-orchestrator - based system maintaining agents in a loop until task completion. (Harnesses & orchestration / Orchestrators & autonomous loops)
README
# Ralph Orchestrator
[](LICENSE)
[](https://www.rust-lang.org/)
[](https://github.com/mikeyobrien/ralph-orchestrator/actions)
[](coverage/index.html)
[](https://github.com/hesreallyhim/awesome-claude-code)
[](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 Homebrew (macOS/Linux)
```bash
brew install ralph-orchestrator
```
### Via Cargo
```bash
cargo install ralph-cli
```
## 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: specs/user-authentication/requirements.md, design.md, implementation-plan.md
# 3. Implement the feature
ralph run -p "Implement the feature in 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.
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, Amp, Copilot CLI, OpenCode
- **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/)
## 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
- **[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*