Ruflo: Multi-Agent AI Orchestration for Claude Code & Codex
Ruflo (formerly Claude Flow) is an open-source meta-harness that sits around Claude Code and Codex and turns them into a coordinated swarm rather than a single chat assistant. It bundles prebuilt agents, swarm topologies, a persistent vector memory, a self-learning loop, and an MCP server so the whole thing plugs into an existing Claude Code or Codex workflow. This guide explains what Ruflo actually adds, where it fits, and where a simpler framework or a managed service is the better call.
What Ruflo is, in one paragraph
An AI agent is a model plus a harness: the model reads and writes tokens, while the harness owns the system prompt, the conversation loop, sandboxing, tools, and memory. Claude Code and Codex are already harnesses. Ruflo is a meta-harness that operates around them, adding agent specifications, federation, a shared memory store, and self-learning on top. It is distributed as an MCP server and as a CLI, and it ships with 100+ prebuilt agents covering coding, security, docs, and other engineering tasks. At the time the reference material was captured, the project had roughly 66k GitHub stars, 1.6k releases, and 7.9k forks; treat those figures as a dated snapshot and check the repository for current numbers.
Why single-agent frameworks struggle with swarms
Most agent frameworks were designed around one assistant in a chat loop: take a message, do work, report back. Swarm orchestration was added later, and the seams show. State and message passing often have to be wired by hand, failure handling is ad hoc, and the infrastructure around memory and failover becomes its own DevOps project. Claude Code and Codex have subagent features, but they do not provide centralized memory management. LangGraph and AutoGen give you fine control, at the cost of defining every agent and every coordination rule yourself. CrewAI's role-based model is closer to turnkey but still needs configuration. Ruflo's pitch is that the coordination patterns, memory, and federation are built in rather than bolted on.
What ships in the box
The feature set is broad enough that it is worth separating the parts you will actually use from the parts you will only touch when something goes wrong. The orchestration layer provides 16 roles across 8 categories, 6 swarm topologies (hierarchical, mesh, and others), and 5 consensus strategies (Byzantine, Raft, Gossip, and others). If you do not want to choose, intelligent routing picks an agent and model for the task; the project claims 89% accuracy for that routing. The learning layer includes SONA (Self-Optimizing Neural Architectures), which lets models keep learning without retraining, and ReasoningBank, which stores and reuses reasoning paths that worked, reducing token use on reasoning-heavy tasks. Twelve background workers can run audits, optimization, and learning without a prompt. Memory is handled by AgentDB, a bundled vector store with HNSW indexes and cross-session persistence that doubles as shared memory for parallel agents. A RAG memory plugin adds hybrid search, graph hops, and diversity ranking. On the infrastructure side, Ruflo supports Claude, GPT, Gemini, Cohere, and Ollama with failover between providers, ships the MCP server, supports zero-trust federation between remote agents, and includes a security audit for vulnerabilities and CVEs plus a defense layer that blocks prompt injections and detects PII.
Reading the benchmarks without over-reading them
Ruflo has published framework-overhead benchmarks against LangGraph, AutoGen, and CrewAI, run on Apple Silicon M-series and on Linux x86_64 with Ubuntu 24.04. Ruflo led on cold start (under 3.93 ms at worst), single-turn dispatch (0.053 ms at worst), and peak memory (under 62 MB, with AutoGen around 78 MB and CrewAI above 250 MB). It placed second to CrewAI on composing 50 tools and on parallel wall time with n=10, 1.5x and 8x behind respectively. The important caveat is that these numbers measure the framework, not the model: a dispatch time of about 50 microseconds is negligible next to an LLM response of a few seconds. The practical read is that low memory makes running many agents in parallel cheap, and low cold start makes container deployment easy. For vector memory, HNSW retrieval was 1.9x faster than brute force at 20k vectors and 3.2x–4.7x faster at 5k vectors, with a small crossover point beyond which approximate nearest-neighbor search wins. These are the project's own published figures, not an independent rerun.
Decision checklist: is Ruflo the right layer?
Use this checklist before installing. If most answers land on the left, Ruflo is a reasonable fit; if most land on the right, a simpler framework or a managed service will save you time.
Install and drive Ruflo
Installation has two paths. On macOS, Linux, WSL, or Git-Bash, the one-line installer is the shortest route. On any platform, including Windows PowerShell and cmd, use the npx wizard or a global npm install. After installing, register the MCP server with Claude Code once so it starts automatically, or launch it directly. From the CLI you can spawn a single typed agent or a whole hive-mind swarm, then check status and memory. The exact commands are preserved in the accompanying protected code modules and should be copied verbatim rather than retyped.
Worked example: a swarm code review
A captured demonstration shows the intended flow. Inside a normal Claude Code session, a single instruction asked Ruflo to raise a swarm against the current folder and audit it for both security and quality problems. In the recorded run, a security-auditor agent and a quality-reviewer agent worked in parallel over the same codebase, with no extra wiring beyond the initial Ruflo setup. Read this as an illustration of the integration pattern, not as a fresh benchmark: the value is that the swarm was invoked from the existing Claude Code workflow rather than from a separate orchestration script. If you reproduce it, expect the agents to share memory through AgentDB and to report back through the same session.
Where Ruflo stops and managed infrastructure begins
Ruflo coordinates agents; it does not supply the infrastructure those agents might need. A data-extraction workflow still needs rotating proxies, headless browsers for JavaScript-rendered pages, anti-bot handling, and structured output. An agent can be asked to build that stack, but it will spend tokens and time doing so, and the result is infrastructure you now operate. A managed scraping API can be used on its own or alongside Ruflo: the API handles proxies, rendering, and extraction, and returns clean output that agents can consume. The division of labor is straightforward — Ruflo decides which agent does what, and the managed service handles the parts of the job that are not really about agent coordination.
Where to go next
The Ruflo repository, user guide, and community Discord are the primary references for current commands and configuration. If your workflow includes scraping or extraction, evaluate a managed API alongside Ruflo rather than asking the swarm to build that infrastructure from scratch. The two layers are complementary, not competing.
| Signal | Choose Ruflo | Choose a simpler framework or managed service |
|---|---|---|
| Number of agents | A team of specialized agents that must share knowledge and coordinate | One agent doing one task, such as simple pair programming |
| Memory needs | Cross-session recall and shared memory across parallel agents | No need for persistent or shared memory |
| Learning needs | Agents should improve from each run | Tasks are simple and stable; learning only adds overhead |
| Host tooling | You already use Claude Code or Codex and want orchestration inside that workflow | You are not using either host harness |
| Customization | You want open-source control over the agent stack | You prefer a fixed, managed workflow |
| Infrastructure outside agent coordination | You are willing to operate it or pair Ruflo with a managed service | You would rather delegate scraping, rendering, and anti-bot handling to a managed API |
Fit guidance reflects the captured reference material; verify current capabilities against the Ruflo repository before committing.
| Surface | Control | What it does |
|---|---|---|
| Install (POSIX) | One-line installer | Installs and initializes Ruflo on macOS, Linux, WSL, or Git-Bash |
| Install (any platform) | npx wizard | Interactive setup that works on Windows PowerShell and cmd |
| Install (any platform) | Global npm install | Installs Ruflo globally instead of running the wizard |
| MCP | mcp start | Launches the Ruflo MCP server |
| MCP + Claude Code | claude mcp add | Registers Ruflo so Claude Code starts the MCP server automatically |
| CLI | agent spawn | Spawns a single typed agent, for example a coder |
| CLI | hive-mind spawn | Spawns a swarm with a task description |
| CLI | hive-mind status | Reports the current state of the swarm |
| CLI | hive-mind memory | Reports memory usage |
Command strings are preserved exactly in the accompanying protected code modules; this map is a reading aid, not a replacement.
Frequently asked questions
Is Ruflo the same as Claude Flow?
Yes. Ruflo was formerly named Claude Flow; the project was renamed and the current repository is under the Ruflo name. The architecture and the meta-harness concept carried over.
Does Ruflo replace Claude Code or Codex?
No. Claude Code and Codex remain the harnesses that run the model. Ruflo is a meta-harness around them, adding agent specifications, coordination, shared memory, and federation. You keep using your existing Claude Code or Codex workflow.
Do I need to understand swarm topologies and consensus strategies to use Ruflo?
No. Ruflo exposes 6 swarm topologies and 5 consensus strategies, but intelligent routing can choose an agent and model for a task without you configuring those details. The project claims 89% accuracy for that routing; treat the figure as the project's own claim.
What is the difference between framework overhead and LLM latency in the benchmarks?
The published benchmarks measure the framework's own overhead — cold start, dispatch, memory — not the model's response time. A dispatch time of about 50 microseconds is negligible next to an LLM response of a few seconds, so the benchmarks tell you about scaling and deployment cost, not about answer quality.
Can Ruflo handle web scraping on its own?
Not by itself. Ruflo coordinates agents; it does not provide proxies, headless browsers, anti-bot handling, or structured extraction. Those can be delegated to a managed scraping API and used alongside Ruflo, with Ruflo deciding which agent does what and the API handling the extraction infrastructure.
When is Ruflo overkill?
When one agent is doing one task. Using Ruflo for a simple pair-programming job is like hiring an engineering team with a manager for work an intern could do. If you do not need shared memory, swarm coordination, or continuous learning, a traditional agent framework is lighter.
# Command 1, installing and initializing
# For POSIX shells (MacOS/Linux/WSL/Git-Bash)
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash
# Alternate command 1, for all platforms
npx ruflo@latest init wizard
# Command 2, for adding Ruflo MCP to Claude Code
claude mcp add ruflo -- npx ruflo@latest mcp start
# One-line installer, POSIX shells only
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash
claude mcp add ruflo -- npx ruflo@latest mcp start