[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-73326":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":14,"stars30d":18,"stars90d":16,"forks30d":16,"starsTrendScore":19,"compositeScore":20,"rankGlobal":10,"rankLanguage":10,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":24,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":41,"readmeContent":42,"aiSummary":43,"trendingCount":16,"starSnapshotCount":16,"syncStatus":44,"lastSyncTime":45,"discoverSource":46},73326,"ralph-orchestrator","mikeyobrien\u002Fralph-orchestrator","mikeyobrien","An improved implementation of the Ralph Wiggum technique for autonomous AI agent orchestration","",null,"Rust",2934,277,26,22,0,16,83,48,29.33,"MIT License",false,"main",true,[26,27,28,29,30,31,32,33,34,35,36,37,38,39,40],"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","2026-06-12 02:03:11","\u003C!-- 2026-01-28 -->\n# Ralph Orchestrator\n\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-blue)](LICENSE)\n[![Rust](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Frust-1.75+-orange)](https:\u002F\u002Fwww.rust-lang.org\u002F)\n[![Build](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Factions\u002Fworkflow\u002Fstatus\u002Fmikeyobrien\u002Fralph-orchestrator\u002Fci.yml?branch=main&label=CI)](https:\u002F\u002Fgithub.com\u002Fmikeyobrien\u002Fralph-orchestrator\u002Factions)\n[![Coverage](https:\u002F\u002Fimg.shields.io\u002Fendpoint?url=https:\u002F\u002Fmikeyobrien.github.io\u002Fralph-orchestrator\u002Fbadges\u002Fcoverage.json)](CONTRIBUTING.md#coverage)\n[![Mentioned in Awesome Claude Code](https:\u002F\u002Fawesome.re\u002Fmentioned-badge.svg)](https:\u002F\u002Fgithub.com\u002Fhesreallyhim\u002Fawesome-claude-code)\n[![Docs](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fdocs-mkdocs-blue)](https:\u002F\u002Fmikeyobrien.github.io\u002Fralph-orchestrator\u002F)\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fdiscord\u002F1482421188700667906?label=Discord&logo=discord&logoColor=white)](https:\u002F\u002Fdiscord.gg\u002FXWUyeUNffh)\n\nA hat-based orchestration framework that keeps AI agents in a loop until the task is done.\n\n> \"Me fail English? That's unpossible!\" - Ralph Wiggum\n\n**[Documentation](https:\u002F\u002Fmikeyobrien.github.io\u002Fralph-orchestrator\u002F)** | **[Getting Started](https:\u002F\u002Fmikeyobrien.github.io\u002Fralph-orchestrator\u002Fgetting-started\u002Fquick-start\u002F)** | **[Presets](https:\u002F\u002Fmikeyobrien.github.io\u002Fralph-orchestrator\u002Fguide\u002Fpresets\u002F)**\n\n## Installation\n\n### Via npm (Recommended)\n\n```bash\nnpm install -g @ralph-orchestrator\u002Fralph-cli\n```\n\n### Via GitHub Releases installer\n\n```bash\ncurl --proto '=https' --tlsv1.2 -LsSf \\\n  https:\u002F\u002Fgithub.com\u002Fmikeyobrien\u002Fralph-orchestrator\u002Freleases\u002Flatest\u002Fdownload\u002Fralph-cli-installer.sh | sh\n```\n\n### Via Cargo\n\n```bash\ncargo install ralph-cli\n```\n\n> Homebrew is not currently published from this repository's automated release flow. Prefer npm, Cargo, or the GitHub Releases installer.\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\u002Fuser-authentication\u002Frequirements.md, design.md, implementation-plan.md\n\n# 3. Implement the feature\nralph run -p \"Implement the feature in specs\u002Fuser-authentication\u002F\"\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 \u002Fusers endpoint\"\n```\n\n## Web Dashboard (Alpha)\n\n> **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:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002Fce5f072f-3d81-44d8-8f2f-88b42b33a3be\" \u002F>\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 \u002Fpath\u002Fto\u002Frepo\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\u002Fworkspace. 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 >= 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:\u002F\u002Fnodejs.org\u002F\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\u002Fbackend 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:\u002F\u002Fghuntley.com\u002Fralph\u002F) — 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 & 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** — `\u002Fstatus`, `\u002Ftasks`, `\u002Frestart` for real-time loop visibility\n\nSee the [Telegram guide](https:\u002F\u002Fmikeyobrien.github.io\u002Fralph-orchestrator\u002Fguide\u002Ftelegram\u002F) for setup instructions.\n\n## Documentation\n\nFull documentation is available at **[mikeyobrien.github.io\u002Fralph-orchestrator](https:\u002F\u002Fmikeyobrien.github.io\u002Fralph-orchestrator\u002F)**:\n\n- [Installation](https:\u002F\u002Fmikeyobrien.github.io\u002Fralph-orchestrator\u002Fgetting-started\u002Finstallation\u002F)\n- [Quick Start](https:\u002F\u002Fmikeyobrien.github.io\u002Fralph-orchestrator\u002Fgetting-started\u002Fquick-start\u002F)\n- [Configuration](https:\u002F\u002Fmikeyobrien.github.io\u002Fralph-orchestrator\u002Fguide\u002Fconfiguration\u002F)\n- [CLI Reference](https:\u002F\u002Fmikeyobrien.github.io\u002Fralph-orchestrator\u002Fguide\u002Fcli-reference\u002F)\n- [Presets](https:\u002F\u002Fmikeyobrien.github.io\u002Fralph-orchestrator\u002Fguide\u002Fpresets\u002F)\n- [Concepts: Hats & Events](https:\u002F\u002Fmikeyobrien.github.io\u002Fralph-orchestrator\u002Fconcepts\u002Fhats-and-events\u002F)\n- [Architecture](https:\u002F\u002Fmikeyobrien.github.io\u002Fralph-orchestrator\u002Fadvanced\u002Farchitecture\u002F)\n\n\n## FAQ\n\n### General\n\n**What is Ralph Orchestrator?**\nRalph 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.\n\n**How is Ralph different from other AI coding tools?**\nUnlike 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.\n\n### Installation & Setup\n\n**What are the system requirements?**\n- Rust 1.75+ (for the `ralph-api` component)\n- Node.js >= 18 + npm (for the web dashboard frontend)\n- An AI coding assistant CLI (Claude Code, Codex, Gemini CLI, etc.)\n\n**Which installation method should I use?**\n- **npm** (recommended for most users): `npm install -g @ralph-orchestrator\u002Fralph-cli`\n- **Cargo**: `cargo install ralph-cli` (best for Rust developers)\n- **GitHub Releases installer**: One-link install with `curl ... | sh`\n\n**Is Homebrew supported?**\nHomebrew is not currently published from this repository's automated release flow. Prefer npm, Cargo, or the GitHub Releases installer.\n\n### Usage\n\n**How do I start a new project with Ralph?**\n```bash\nralph init --backend claude\nralph plan \"Add user authentication with JWT\"\nralph run -p \"Implement the feature in specs\u002Fuser-authentication\u002F\"\n```\n\n**What backends does Ralph support?**\nClaude Code, Kiro, Gemini CLI, Codex, Amp, Copilot CLI, and OpenCode.\n\n**What is the \"hat system\"?**\nRalph 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.\n\n### RObot (Human-in-the-Loop)\n\n**What is RObot?**\nRObot enables human interaction during orchestration via Telegram. Agents can ask questions and block until answered; humans can send proactive guidance mid-loop.\n\n**How do I set up Telegram integration?**\n```bash\nralph bot onboard --telegram   # guided setup\nralph bot status               # verify config\nralph bot test                 # send a test message\n```\n\n### Web Dashboard\n\n**How do I access the web dashboard?**\nRun `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.\n\n**Can I customize the dashboard ports?**\nYes: `ralph web --backend-port 4000 --frontend-port 8080`\n\n### MCP Server\n\n**How do I run Ralph as an MCP server?**\n```bash\nralph mcp serve --workspace-root \u002Fpath\u002Fto\u002Frepo\n```\nEach MCP server instance is scoped to a single workspace root. For multi-repo use, run one instance per workspace.\n\n### Troubleshooting\n\n**Ralph fails to start with \"node_modules not found\"**\nRun `npm install` in the project directory, or let `ralph web` auto-detect and install on first run.\n\n**How do I set up Node.js if not installed?**\nUse nvm (recommended): `nvm install` (reads `.nvmrc`), or install directly from https:\u002F\u002Fnodejs.org\u002F\n\n**Where can I get help?**\n- Join our [Discord server](https:\u002F\u002Fdiscord.gg\u002FXWUyeUNffh)\n- Report bugs on the [Issue Tracker](https:\u002F\u002Fgithub.com\u002Fmikeyobrien\u002Fralph-orchestrator\u002Fissues)\n- Read full documentation at [mikeyobrien.github.io\u002Fralph-orchestrator](https:\u002F\u002Fmikeyobrien.github.io\u002Fralph-orchestrator\u002F)\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 & 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:\u002F\u002Fdiscord.gg\u002FXWUyeUNffh) 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:\u002F\u002Fgithub.com\u002Fmikeyobrien\u002Fralph-orchestrator\u002Fissues).\n\n## Acknowledgments\n\n- **[Geoffrey Huntley](https:\u002F\u002Fghuntley.com\u002Fralph\u002F)** — Creator of the Ralph Wiggum technique\n- **[Strands Agents SOP](https:\u002F\u002Fgithub.com\u002Fstrands-agents\u002Fagent-sop)** — Agent SOP framework\n- **[ratatui](https:\u002F\u002Fratatui.rs\u002F)** — Terminal UI framework\n\n---\n\n*\"I'm learnding!\" - Ralph Wiggum*\n","Ralph Orchestrator 是一个用于自主AI代理编排的框架，基于Rust语言实现。它通过一种称为“Ralph Wiggum”的技术让AI代理在一个循环中持续工作直到任务完成，支持多种后端如Claude等，并提供命令行工具及Web界面（Alpha版本）进行交互与监控。该框架特别适用于需要自动化处理复杂或重复性高的开发任务场景，比如功能规划、代码生成和测试等。其简洁易用的CLI接口允许用户快速初始化项目并开始执行计划，而正在积极开发中的Web仪表盘则进一步增强了项目的可管理性和可视化能力。",2,"2026-06-11 03:45:02","high_star"]