Ruflo (formerly Claude Flow): The Swarm Meta-Harness and Which Claims You Can Check

Ruflo is a very popular but very large agent framework, and its own README is unusually frank about which parts are proven. Formerly called Claude Flow, the project from ruvnet has about 74,800 stars, 8,900 forks and 9,598 commits, is MIT-licensed, and describes itself as "the execution layer around Claude Code and Codex." It trended on GitHub this week. This guide covers what it is, how to install it, which numbers are vendor-reported, and the limits the maintainers list for themselves.

For comparable projects, see our guides to ECC and Superpowers, and the broader ranking of open and closed agent harnesses.

TL;DR: questions answered

What it adds on top of your agent

The README groups the features into a handful of layers:

• Agents and swarms. More than 100 specialized agents, with hierarchical, mesh and adaptive swarm topologies and consensus between them.
• Memory. HNSW-indexed vector memory, called AgentDB, with persistence across sessions. HNSW is a graph index for approximate nearest-neighbor search.
• Learning. Named components include SONA patterns, ReasoningBank and trajectory learning. The README itself says results depend on configured memory and feedback quality.
• Federation. Cross-machine agent collaboration using mTLS and ed25519 identity, with PII filtering before outbound messages. Remote agents start untrusted and are verified by challenge-response.
• Plugins. 35 plugins in the marketplace for testing, security, documentation and observability.
• Console and TUI. A visual agent cockpit (/ruflo) and a terminal UI (npx ruflo tui).
• MetaHarness. Grades an agent setup from 1 to 100, scans tool configs and can eject a project.

In plain terms, Ruflo tries to turn a single coding agent into a coordinated team with shared memory. That is the same direction as the agent-swarm company OS and the Cursor swarm economics work, with the difference that Ruflo ships as a layer over tools you already use.

How to install it

The README offers several routes:

# CLI setup wizard
npx ruflo@latest init wizard

# or install globally
npm install -g ruflo@latest

# register as an MCP server in Claude Code
claude mcp add claude-flow -- npx ruflo@latest mcp start

For Claude Code plugins that add slash commands only:

/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/reload-plugins

The plugin route requires Claude Code 2.1.287 or later. For any other MCP client the README gives the command npx with args -y ruflo@latest mcp start. Two notes from us. First, @latest means you get whatever was published most recently; pin a version in anything you rely on. Second, the README says hook support "depends on the client", so Codex and generic MCP clients will not get the full Claude Code experience. See our Claude Code commands reference for the surrounding plugin commands.

Claims versus what you can check

Every number below is from the README, and the README labels benchmarks as published by the project. We did not reproduce them.

Two points of context. The memory-index comparison is honest about the crossover: approximate nearest-neighbor search only beats a brute-force scan once the corpus is large enough. For a typical project memory of a few thousand items, that speedup may not matter. And a framework comparison that measures cold start and memory footprint tells you about overhead, not about whether the agents solve tasks better. For that you need task-level evaluations on your own work, like those in our post on agent teams versus single agents.

The limitations the README states

This is the most useful part of the page:

• Several demos use sample data or replayed renderer frames. The README says they are not evidence of completed swarm work or memory recall.
• Creating a mission "does not mean the feature has been implemented."
• Local learning requires embeddings and configured learning modules, and an LLM may still be used for agent execution.
• The console's native host and AI provider execution are "not demonstrated."
• Benchmarks are vendor-published, and approximate-search gains appear only above a crossover point.
• The documentation mixes package names (ruflo, claude-flow), and issue links point to the claude-flow repository.

With 690 open issues and 358 open pull requests, expect rough edges. The version number is also hard to pin down: no single release appears on the README page, the install uses @latest, and the benchmarks section cites v3.8.0.

Security: read this before you give it your repo

The README is specific about trust boundaries:

• Plugins and mods run with your account's permissions and are "not sandboxed." Review code before installing.
• Claude control of the console defaults to read plus ask. Permission levels are read, write, manage and full, with ask or auto approval. Network, spending and destructive actions require confirmation even in auto mode.
• Federation treats remote agents as untrusted until verified with mTLS and an ed25519 challenge.
• Built-in defenses include AIDefence for prompt-injection and PII detection, CVE remediation, and ruflo verify, which checks installed bytes against a signed witness. A SECURITY.md is included.

A swarm multiplies the number of agents holding tools, and federation extends that across machines, so the damage from one prompt-injected agent grows with it. Use the strictest permission mode that still lets you work, run in a container or VM, and keep secrets out of the working directory. For runtime enforcement, AgentBeam, the agent security platform from the explainx.ai team, stops AI agents before they take dangerous actions. The risk pattern is similar to the ones we discuss in Capsem's VM sandbox post.

Should you use it?

A reasonable yes: you already work with Claude Code or Codex, want persistent vector memory and orchestration without building it, and are willing to read code and pin versions.

A reasonable no: you want a small, auditable setup. A 100-agent, 300-tool surface is a lot to review, and each added tool consumes context and widens what a compromised prompt can reach.

A fair test: install only the core plugin, enable memory, and run three tasks you already know the answer to. Compare cost, time and correctness against plain Claude Code. If swarms do not beat a single agent on your tasks, you have your answer, whatever the README's cold-start chart says.

A three-day evaluation plan

Because the performance numbers are the project's own, build your own evidence before committing a team to it.

Day 1: install and inspect. Install only the core plugin in a throwaway repository. List the tools and commands it registers and compare the count with the README's 314 MCP tools. Read what each hook does at session start, and check which files it writes. Note the cost of simply having it loaded: start a session and look at how much context is consumed before you type anything.

Day 2: memory. Enable the vector memory and feed it a few facts about a real project, such as naming conventions and architecture decisions. In a fresh session, ask questions that need those facts. Record whether it recalls them, how often it recalls wrong ones, and what happens when two facts conflict. The README warns that learning quality depends on configured memory and feedback, so your results will depend on setup.

Day 3: swarm versus single agent. Pick three tasks of increasing size: a bug fix, a feature touching three files and a refactor. Run each with plain Claude Code and with a Ruflo swarm. Measure wall-clock time, tokens, number of human interventions and whether tests pass. Swarms tend to help on tasks that split cleanly and hurt on tightly coupled ones, because coordination costs tokens. If your tasks are mostly the second kind, the single agent will likely win.

Write down the result with the version you tested, since @latest will have moved by the time you revisit it.

What people are asking

Is Ruflo the same as Claude Flow? Yes. The README says Ruflo is formerly Claude Flow, and the old package name still appears in the MCP registration command and in issue links.

Does it replace Claude Code? No. It is a layer around Claude Code and Codex and depends on them. If you stop using those tools, there is nothing to run it on.

Do I need a vector database? The memory layer ships its own indexed store, so you do not run a separate database, but check the README for the persistence format before you rely on it for important context.

How is it different from skills collections? Skills are instructions that load on demand. Ruflo adds runtime machinery: swarms, a memory index, a console and a federation protocol. That brings more capability and a larger attack surface.

Related reading

• ECC: 71 agents and 311 skills
• Superpowers skills framework
• Official Claude Code plugin directory
• Top 10 open and closed agent harnesses
• Agent teams vs single agent: token cost and quality
• What is MCP?

Counts, versions and claims are from the Ruflo README on October 15, 2026 and change often. Check the repository before installing.