{"id":35835818,"url":"https://github.com/mikeyobrien/ralph-orchestrator","last_synced_at":"2026-03-16T03:03:16.003Z","repository":{"id":313679554,"uuid":"1052259802","full_name":"mikeyobrien/ralph-orchestrator","owner":"mikeyobrien","description":"An improved implementation of the Ralph Wiggum technique for autonomous AI agent orchestration","archived":false,"fork":false,"pushed_at":"2026-02-21T15:03:32.000Z","size":10122,"stargazers_count":1875,"open_issues_count":13,"forks_count":192,"subscribers_count":24,"default_branch":"main","last_synced_at":"2026-02-21T21:00:37.423Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mikeyobrien.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-07T18:17:13.000Z","updated_at":"2026-02-21T16:04:15.000Z","dependencies_parsed_at":null,"dependency_job_id":"428e7ea0-2cdb-40f9-a817-c4e44ed46b44","html_url":"https://github.com/mikeyobrien/ralph-orchestrator","commit_stats":null,"previous_names":["mikeyobrien/ralph-orchestrator"],"tags_count":34,"template":false,"template_full_name":null,"purl":"pkg:github/mikeyobrien/ralph-orchestrator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeyobrien%2Fralph-orchestrator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeyobrien%2Fralph-orchestrator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeyobrien%2Fralph-orchestrator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeyobrien%2Fralph-orchestrator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mikeyobrien","download_url":"https://codeload.github.com/mikeyobrien/ralph-orchestrator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mikeyobrien%2Fralph-orchestrator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29809280,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-24T22:43:48.403Z","status":"online","status_checked_at":"2026-02-25T02:00:07.329Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-01-08T00:11:22.148Z","updated_at":"2026-03-16T03:03:15.997Z","avatar_url":"https://github.com/mikeyobrien.png","language":"Rust","funding_links":[],"categories":["Workflows \u0026 Knowledge Guides 🧠","Autonomous Loop Runners","Agent Orchestration","Multi-Agent Systems","Code \u0026 Developer Tools","Implementations","Harnesses \u0026 orchestration","工作流程与知识指南 🧠"],"sub_categories":["Ralph Wiggum","Parallel Processing","Standalone Implementations","Orchestrators \u0026 autonomous loops"],"readme":"\u003c!-- 2026-01-28 --\u003e\n# Ralph Orchestrator\n\n[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n[![Rust](https://img.shields.io/badge/rust-1.75+-orange)](https://www.rust-lang.org/)\n[![Build](https://img.shields.io/github/actions/workflow/status/mikeyobrien/ralph-orchestrator/ci.yml?branch=main\u0026label=CI)](https://github.com/mikeyobrien/ralph-orchestrator/actions)\n[![Coverage](https://img.shields.io/badge/coverage-65%25-yellowgreen)](coverage/index.html)\n[![Mentioned in Awesome Claude Code](https://awesome.re/mentioned-badge.svg)](https://github.com/hesreallyhim/awesome-claude-code)\n[![Docs](https://img.shields.io/badge/docs-mkdocs-blue)](https://mikeyobrien.github.io/ralph-orchestrator/)\n[![Discord](https://img.shields.io/discord/1482421188700667906?label=Discord\u0026logo=discord\u0026logoColor=white)](https://discord.gg/XWUyeUNffh)\n\nA hat-based orchestration framework that keeps AI agents in a loop until the task is done.\n\n\u003e \"Me fail English? That's unpossible!\" - Ralph Wiggum\n\n**[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/)**\n\n## Installation\n\n### Via npm (Recommended)\n\n```bash\nnpm install -g @ralph-orchestrator/ralph-cli\n```\n\n### Via Homebrew (macOS/Linux)\n\n```bash\nbrew install ralph-orchestrator\n```\n\n### Via Cargo\n\n```bash\ncargo install ralph-cli\n```\n\n## Quick Start\n\n```bash\n# 1. Initialize Ralph with your preferred backend\nralph init --backend claude\n\n# 2. Plan your feature (interactive PDD session)\nralph plan \"Add user authentication with JWT\"\n# Creates: specs/user-authentication/requirements.md, design.md, implementation-plan.md\n\n# 3. Implement the feature\nralph run -p \"Implement the feature in specs/user-authentication/\"\n```\n\nRalph iterates until it outputs `LOOP_COMPLETE` or hits the iteration limit.\n\nFor simpler tasks, skip planning and run directly:\n\n```bash\nralph run -p \"Add input validation to the /users endpoint\"\n```\n\n## Web Dashboard (Alpha)\n\n\u003e **Alpha:** The web dashboard is under active development. Expect rough edges and breaking changes.\n\n\u003cimg width=\"1513\" height=\"1128\" alt=\"image\" src=\"https://github.com/user-attachments/assets/ce5f072f-3d81-44d8-8f2f-88b42b33a3be\" /\u003e\n\nRalph includes a web dashboard for monitoring and managing orchestration loops.\n\n```bash\nralph web                              # starts Rust RPC API + frontend + opens browser\nralph web --no-open                    # skip browser auto-open\nralph web --backend-port 4000          # custom RPC API port\nralph web --frontend-port 8080         # custom frontend port\nralph web --legacy-node-api            # opt into deprecated Node tRPC backend\n```\n\n### MCP Server Workspace Scope\n\n`ralph mcp serve` is scoped to a single workspace root per server instance.\n\n```bash\nralph mcp serve --workspace-root /path/to/repo\n```\n\nPrecedence is:\n\n1. `--workspace-root`\n2. `RALPH_API_WORKSPACE_ROOT`\n3. current working directory\n\nFor multi-repo use, run one MCP server instance per repo/workspace. Ralph's current\ncontrol-plane APIs persist config, tasks, loops, planning sessions, and collections\nunder a single workspace root, so server-per-workspace is the deterministic model.\n\n**Requirements:**\n- Rust toolchain (for `ralph-api`)\n- Node.js \u003e= 18 + npm (for the frontend)\n\nOn first run, `ralph web` auto-detects missing `node_modules` and runs `npm install`.\n\nTo set up Node.js:\n\n```bash\n# Option 1: nvm (recommended)\nnvm install    # reads .nvmrc\n\n# Option 2: direct install\n# https://nodejs.org/\n```\n\nFor development:\n\n```bash\nnpm install              # install frontend + legacy backend deps\nnpm run dev:api          # Rust RPC API (port 3000)\nnpm run dev:web          # frontend (port 5173)\nnpm run dev              # frontend only (default)\nnpm run dev:legacy-server  # deprecated Node backend (optional)\nnpm run test             # all frontend/backend workspace tests\n```\n\n## MCP Server Mode\n\nRalph can run as an MCP server over stdio for MCP-compatible clients:\n\n```bash\nralph mcp serve\n```\n\nUse this mode from an MCP client configuration rather than an interactive terminal workflow.\n\n## What is Ralph?\n\nRalph implements the [Ralph Wiggum technique](https://ghuntley.com/ralph/) — autonomous task completion through continuous iteration. It supports:\n\n- **Multi-Backend Support** — Claude Code, Kiro, Gemini CLI, Codex, Amp, Copilot CLI, OpenCode\n- **Hat System** — Specialized personas coordinating through events\n- **Backpressure** — Gates that reject incomplete work (tests, lint, typecheck)\n- **Memories \u0026 Tasks** — Persistent learning and runtime work tracking\n- **5 Supported Builtins** — `code-assist`, `debug`, `research`, `review`, and `pdd-to-code-assist`, with more patterns documented as examples\n\n## RObot (Human-in-the-Loop)\n\nRalph supports human interaction during orchestration via Telegram. Agents can ask questions and block until answered; humans can send proactive guidance at any time.\n\nQuick onboarding (Telegram):\n\n```bash\nralph bot onboard --telegram   # guided setup (token + chat id)\nralph bot status               # verify config\nralph bot test                 # send a test message\nralph run -c ralph.bot.yml -p  \"Help the human\"\n```\n\n```yaml\n# ralph.yml\nRObot:\n  enabled: true\n  telegram:\n    bot_token: \"your-token\"  # Or RALPH_TELEGRAM_BOT_TOKEN env var\n```\n\n- **Agent questions** — Agents emit `human.interact` events; the loop blocks until a response arrives or times out\n- **Proactive guidance** — Send messages anytime to steer the agent mid-loop\n- **Parallel loop routing** — Messages route via reply-to, `@loop-id` prefix, or default to primary\n- **Telegram commands** — `/status`, `/tasks`, `/restart` for real-time loop visibility\n\nSee the [Telegram guide](https://mikeyobrien.github.io/ralph-orchestrator/guide/telegram/) for setup instructions.\n\n## Documentation\n\nFull documentation is available at **[mikeyobrien.github.io/ralph-orchestrator](https://mikeyobrien.github.io/ralph-orchestrator/)**:\n\n- [Installation](https://mikeyobrien.github.io/ralph-orchestrator/getting-started/installation/)\n- [Quick Start](https://mikeyobrien.github.io/ralph-orchestrator/getting-started/quick-start/)\n- [Configuration](https://mikeyobrien.github.io/ralph-orchestrator/guide/configuration/)\n- [CLI Reference](https://mikeyobrien.github.io/ralph-orchestrator/guide/cli-reference/)\n- [Presets](https://mikeyobrien.github.io/ralph-orchestrator/guide/presets/)\n- [Concepts: Hats \u0026 Events](https://mikeyobrien.github.io/ralph-orchestrator/concepts/hats-and-events/)\n- [Architecture](https://mikeyobrien.github.io/ralph-orchestrator/advanced/architecture/)\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards.\n\n## License\n\nMIT License — See [LICENSE](LICENSE) for details.\n\n## 💬 Community \u0026 Support\n\nJoin the **ralph-orchestrator** community to discuss AI agent patterns, get help with your implementation, or contribute to the roadmap.\n\n* **Discord**: [Join our server](https://discord.gg/XWUyeUNffh) to chat with the maintainers and other users in real-time.\n* **GitHub Issues**: For bug reports and formal feature requests, please use the [Issue Tracker](https://github.com/mikeyobrien/ralph-orchestrator/issues).\n\n## Acknowledgments\n\n- **[Geoffrey Huntley](https://ghuntley.com/ralph/)** — Creator of the Ralph Wiggum technique\n- **[Strands Agents SOP](https://github.com/strands-agents/agent-sop)** — Agent SOP framework\n- **[ratatui](https://ratatui.rs/)** — Terminal UI framework\n\n---\n\n*\"I'm learnding!\" - Ralph Wiggum*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeyobrien%2Fralph-orchestrator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmikeyobrien%2Fralph-orchestrator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmikeyobrien%2Fralph-orchestrator/lists"}