ralph-orchestrator

Name: ralph-orchestrator
Author: mikeyobrien

Warning

An improved implementation of the Ralph Wiggum technique for autonomous AI agent orchestration

2,993stars

279forks

Rust

Installation

# Add to your Claude Code skills
git clone https://github.com/mikeyobrien/ralph-orchestrator

Getting Started

Guides for using ai agents skills like ralph-orchestrator.

Caveman: Cut Claude Token Use by 65%
How agent-side prompt compression works, when to use it, and when not to.
What is an AI Skills Marketplace?
Definitions, how marketplaces work, and how to choose between them in 2026.
Getting Started with AI Skills

Security ReportWarning

Last scanned: 4/22/2026

{
  "issues": [
    {
      "type": "npm-audit",
      "message": "@esbuild-kit/core-utils: Vulnerability found",
      "severity": "medium"
    },
    {
      "type": "npm-audit",
      "message": "@esbuild-kit/esm-loader: Vulnerability found",
      "severity": "medium"
    },
    {
      "type": "npm-audit",
      "message": "ajv: ajv has ReDoS when using `$data` option",
      "severity": "medium"
    },
    {
      "type": "npm-audit",
      "message": "drizzle-kit: Vulnerability found",
      "severity": "medium"
    },
    {
      "type": "npm-audit",
      "message": "drizzle-orm: Drizzle ORM has SQL injection via improperly escaped SQL identifiers",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "esbuild: esbuild enables any website to send any requests to the development server and read the response",
      "severity": "medium"
    },
    {
      "type": "npm-audit",
      "message": "fastify: Fastify Vulnerable to DoS via Unbounded Memory Allocation in sendWebStream",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "picomatch: Picomatch: Method Injection in POSIX Character Classes causes incorrect Glob Matching",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "rollup: Rollup 4 has Arbitrary File Write via Path Traversal",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "vite: Vite Vulnerable to Path Traversal in Optimized Deps `.map` Handling",
      "severity": "high"
    },
    {
      "type": "npm-audit",
      "message": "yaml: yaml is vulnerable to Stack Overflow via deeply nested YAML collections",
      "severity": "medium"
    }
  ],
  "status": "WARNING",
  "scannedAt": "2026-04-22T06:02:21.748Z",
  "semgrepRan": false,
  "npmAuditRan": true,
  "pipAuditRan": true
}

README.md

Frequently Asked Questions

What is ralph-orchestrator?

ralph-orchestrator is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by mikeyobrien. An improved implementation of the Ralph Wiggum technique for autonomous AI agent orchestration. It has 2,993 GitHub stars.

Is ralph-orchestrator safe to use?

ralph-orchestrator returned warnings in SkillsLLM's automated security scan. It has no critical vulnerabilities, but review the flagged issues in the Security Report section before adding it to your workflow.

How do I install ralph-orchestrator?

Clone the repository with "git clone https://github.com/mikeyobrien/ralph-orchestrator" and add it to your Claude Code skills directory (see the Installation section above).

What programming language is ralph-orchestrator written in?

ralph-orchestrator is primarily written in Rust. It is open-source under mikeyobrien on GitHub, so you can review or fork the full source.

Are there alternatives to ralph-orchestrator?

Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh ralph-orchestrator against similar tools.

Agentic AI for Beginners

Build your first AI agent from scratch - tool use, ReAct pattern, memory, deployment

41 minBeginner

Comments (0)

to leave a comment.

No comments yet. Be the first to share your thoughts!

Related Skills

superpowers

by obra

An agentic skills framework & software development methodology that works.

234,966

Developers Also Liked

Based on votes and bookmarks from developers who liked this skill

everything-claude-code

by affaan-m

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

185,940

Chaterm awesome-agent-skills

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:

--workspace-root
RALPH_API_WORKSPACE_ROOT
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
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:

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, and OpenCode.

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 pro