Ruflo Review: The Claude Code Harness Behind 77K Stars

TL;DR

Ruflo (ruvnet/ruflo), formerly Claude Flow, is an “agent meta-harness” for Claude Code and Codex. It promises 100+ specialized agents, coordinated swarms, self-learning vector memory, cross-machine “federation”, a terminal console and a marketplace of 35 Claude Code plugins. One npx ruflo init writes all of it into your project.

Facts as of October 20, 2026:

77,473 GitHub stars, 9,121 forks; on GitHub Trending this week (2,543 stars this week).
665 open issues (issues only, not pull requests).
License: MIT.
Latest release: v3.58.1, published October 20, 2026 — the 28th release this month. The ruflo npm package had 36,034 downloads in the week of October 12–18; the old claude-flow name had 7,033.
First commit June 2, 2025, by Reuven Cohen (rUv), who has made 8,441 of the commits.

Not run by us: our hands-on lab (a throwaway GitHub Actions container) could not start today because GitHub refused the job over a billing limit on the account. Everything below comes from the README, the release notes, the source tree, the project’s own audit documents and the public issue tracker. We did not install ruflo or run any of its commands.

Our verdict: Ruflo is the most ambitious Claude Code add-on on GitHub, and parts of it are real — its own May 2026 audit measured a working learning loop. But its marketing has repeatedly run ahead of its code: two independent audits and the project’s own review found fabricated speed-ups, stub tools and hooks that do nothing. The maintainer now fixes these in public, fast. Install the single-plugin path to try it; adopt the full init only after you have read what it writes into your repo.

What Ruflo actually is

The README’s own one-liner is “Agent = Model + Harness”. Claude Code or Codex is the model-plus-tools; Ruflo wraps it in an extra layer of coordination:

Agents: markdown agent definitions (coder, tester, reviewer, architect, security auditor and so on) that Claude Code can delegate to. The CLI path ships 98 of them.
MCP server: a single server exposing what the README calls “314 MCP tools” for memory, swarm state, routing, hooks and neural features.
Hooks: Claude Code hooks that fire on edits, shell commands, compaction and subagent starts, and route tasks or record outcomes.
Memory: a SQLite store with an HNSW vector index (“AgentDB”), plus a “ReasoningBank” of patterns that get more or less trusted as tasks succeed or fail.
Console: a terminal cockpit (/ruflo inside Claude Code, or npx ruflo tui standalone) showing workflows, agents, tokens and cost.
Plugins: 35 Claude Code plugins in its own marketplace, from ruflo-swarm and ruflo-testgen to a ruflo-neural-trader with “112+ tools”.

The README labels its architecture diagram “a conceptual flow, not a live execution trace”. Disclaimers like that are new, for reasons covered below.

Two ways to install

The README is unusually clear that the two install paths are very different products.

	Claude Code plugin	CLI (`npx ruflo init`)
What you get	Slash commands, a few skills, agent definitions	”Full Ruflo loop”: 98 agents, 60+ commands, 30 skills, MCP server, hooks, daemon
Files in your workspace	Zero	`.claude/`, `.claude-flow/`, `CLAUDE.md`, helpers, settings
MCP server	Only via `ruflo-core`	Yes
Hooks	No	Yes

Path A: plugins only (the low-risk way to try it)

Inside Claude Code 2.1.287 or later:

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

ruflo-core registers its own MCP server; its tools appear as mcp__plugin_ruflo-core_ruflo__* (for example mcp__plugin_ruflo-core_ruflo__memory_store). The README warns that the separate ruflo-mods plugin “run[s] with your account’s permissions and [is] not sandboxed, so read the code first.”

Path B: the full CLI install

# interactive
npx ruflo@latest init wizard

# non-interactive
npx ruflo@latest init

# or globally
npm install -g ruflo@latest

To use it as an MCP server from Codex or any client that supports stdio servers:

npx -y ruflo@latest mcp start

# Claude Code
claude mcp add claude-flow -- npx ruflo@latest mcp start

Ruflo needs Node 20 or later; the npm package unpacks to about 8.2 MB before dependencies.

The README also offers a curl ... | bash one-liner; given the history below, we would skip it.

Removing it

After users complained they could not uninstall it (issues #373, #670, #710), the maintainer added ruflo cleanup in March 2026. It defaults to a dry run; --force actually deletes .claude/, .swarm/, data/ and the other directories it created. Run the dry run first if your project already has its own .claude/ configuration.

What the console does

The newest focus is ruflo-console, an “agent cockpit” with Overview, Cost, Swarm, Events and Missions pages. Its most interesting feature is Claude control: Claude can drive the console itself at a permission level you choose (read, write, manage or full) with “ask” or “auto” approval. The default is read + ask. The README says network, spending and destructive actions still need confirmation even in auto mode, and a “Take back control” button stops it.

The README is careful about what its demo proves: “creating a mission does not mean the feature has been implemented”, and the workflow animation “uses sample data”. The console is a dashboard over Ruflo’s state, not proof that the swarm did work.

Federation

Federation lets Ruflo installations on different machines exchange work. The README says peers prove identity with mTLS plus ed25519, outbound messages pass a 14-type PII detector, and trust scores upgrade slowly and downgrade instantly. We found no independent report of a production federation deployment. Treat it as an experiment.

The credibility problem — and how it is changing

You cannot review Ruflo honestly without its audit history. Three documents matter.

1. The March 2026 security audit (#1375). A user reported, among other things, that versions 3.1.0-alpha.55 through 3.5.2 shipped an obfuscated preinstall script that deleted directories under ~/.npm/_npx/ and cache index files mentioning claude-flow or ruflo, with errors suppressed; that an SQL-injection report (#1030) had been open since January; that npx was on the “safe executor” allowlist; and that there was no uninstall path. The report also repeated an earlier claim that MCP tool descriptions told Claude to add the repository owner as a contributor.

The maintainer replied within two days and shipped v3.5.40: parameterized queries, the preinstall script removed, npx dropped from the allowlist, a SECURITY.md, and ruflo cleanup. On the tool-description claim he wrote that he had “searched the current codebase and there are no instructions in tool descriptions to add anyone as a contributor” and asked for a specific tool name. The issue was closed.

2. The April 2026 independent audit. A second auditor (roman-rr) published a gist titled “300+ MCP Tools Exposed — 99% Theater, 1% Real”. Testing v3.5.51, they reported that agent_spawn created an in-memory record that stayed idle forever, that a WASM agent answered “echo: ”, that Raft consensus verifySignature() returned true unconditionally, and that “hive-mind” was Claude Code launched with --dangerously-skip-permissions and a long prompt. A Reddit thread built on it, “Do not install Ruflo into your Claude Code workflow until you read this: 99% Fake / 1% Real”, spread widely.

3. The project’s own May 2026 audit. To its credit, the project then commissioned a measurement-based audit of its intelligence system (version 3.10.6) and committed it to the repo. Its findings cut both ways:

Real: “The learning loop is real.” A success verdict raised a pattern’s confidence from 0.906 to 1.0 and a failure lowered it to 0.952, persisted across processes. Q-learning routing feedback changed the next routing decision. Int8 quantization measured 3.92× memory saving; the mixture-of-experts gate converged.
Not real: “HNSW 150x–12,500x faster” measured 1.48× at peak and was slower than brute force below about 5,000 vectors. A “Flash Attention 2.49–7.47×” figure was “fabricated at runtime” with 2.49 + Math.random()*4.98. When the ONNX embedding model failed to build, the system silently fell back to mock embeddings still labeled as the real model.
A critical bug: route feedback -r -1.0 was parsed as +1.00, so following the documented way to punish a bad agent rewarded it.

Several of those findings are visibly fixed on main today. The Flash Attention line now reads flashSpeedup = 0; // 0 = unmeasured (no fabrication). The README’s HNSW claim is now “~1.9x faster at N=20k, ~3.2x–4.7x at N=5k vs brute force … ANN wins above the crossover, ties/loses at small N” — with a link to the audit and the benchmark script. And hive-mind now adds --dangerously-skip-permissions only when you pass that flag explicitly; the source comment calls this a “behavior change”.

The pattern continues in the open issue tracker, which is full of precise, self-filed defect reports. Examples from the past week:

#4200: a fresh ruflo init wires six hooks (pre-edit, post-bash, compact-manual, compact-auto, status, notify) that the shipped hook-handler.cjs has no handler for. Each prints [OK] and exits, costing about 130 ms per call.
#4199: the local-LLM module “never learns from forwarded trajectories”, and a MicroLoRA adapter stays at zero.
#4201: a “witness” manifest presented as cryptographic verification can be re-signed by anyone, because the seed is derived from the public commit hash. The maintainer agreed and said it does not affect npm publish signing.
#4249: a memory backend “calls a native HNSW controller that has never existed in the real agentdb package”.

And today’s v3.58.1 release fixes a path-traversal bug (CWE-22): the hooks_codemod tool — which the release notes call “live, CLAUDE.md-recommended” — checked containment with an unanchored startsWith(cwd), so a sibling directory with a matching name prefix could be read and written.

The fair reading: Ruflo is not a scam, and it is not the self-organizing AI operating system its tagline implies. It is a very large, fast-moving codebase — 28 releases in October alone — where real mechanisms sit next to decorative ones, and the gap is now documented by the project itself (“Dream Cycle” issues are filed nightly). That makes it more trustworthy than it was in March. It does not make every tool in the 314-tool list do what its name says.

Who it is for

Good fit:

Developers who enjoy tinkering with agent setups and want a large catalog of ready-made agent definitions, skills and slash commands to borrow from.
People who want a cost and token dashboard beside Claude Code — the console is a concrete, inspectable feature.
Teams experimenting with persistent cross-session memory who will verify retrieval themselves.

Poor fit:

Production repositories where you cannot audit what init writes into .claude/ and CLAUDE.md.
Anyone who wants a small, predictable tool. Compare a focused add-on such as Context Mode, which does one thing (shrink tool output), or OpenRig for a narrower multi-agent harness.

Honest limitations

Claims need checking one by one. The project’s own audit found headline numbers were “hardcoded doc strings” as recently as May.
init changes a lot, including hooks that run on every edit and shell command — some no-ops as of 3.56.10.
Security-sensitive tools. Mods run unsandboxed with your account’s permissions; a path-traversal bug in a recommended tool was fixed only today.
Release churn. v3.57.1 through v3.58.1 shipped within about 16 hours. @latest in an MCP config means your agent’s tools can change overnight.
665 open issues and a bus factor of essentially one human maintainer; the next-largest contributors are an automation account and Claude itself.
Token cost. Hooks, memory injection and a 314-tool MCP surface all spend context. The April audit called it “5x token waste”; nobody has published a neutral measurement of the current version.

FAQ

Is Ruflo the same as Claude Flow?

Yes. Claude Flow was renamed Ruflo in early 2026 (v3.5.0 was announced as “So long Claude Flow, hello RuFlo”). The repository kept its history from June 2, 2025, the claude-flow npm package still publishes alongside ruflo, and the MCP server is still registered as claude-flow in the README’s Claude Code example.

Is Ruflo safe to install?

It is MIT-licensed open source with a SECURITY.md and fast public fixes, but it has a real history: an obfuscated preinstall script in earlier versions (removed in v3.5.40), an SQL-injection bug (fixed the same release) and a path-traversal bug fixed in v3.58.1 today. Use the plugin-only path first, pin a version instead of @latest, and read the mods before enabling them.

Does Ruflo work with Codex?

Yes, as an MCP server via npx -y ruflo@latest mcp start. The console and mods are Claude Code only.

Do the swarms actually run agents in parallel?

It depends on the command. The April 2026 independent audit found agent_spawn and task tools only recorded state, while hive-mind spawn --claude launched Claude Code with a coordinating prompt. The project’s own README now says a plan or an agent record “does not mean work has happened”. Expect real work to be done by Claude Code subagents, with Ruflo tracking and routing around them.

Does the self-learning memory really learn?

Partly. The project’s May 2026 audit measured a genuine loop in which task outcomes change stored pattern confidence and routing choices across sessions. The same audit found inert components (a WASM LoRA adapter whose output never changed) and a bug that inverted negative feedback. Open issues in October still report learning paths that do not persist.

How do I uninstall Ruflo?

Run ruflo cleanup (a dry run), then ruflo cleanup --force. Remove the MCP server from your client config, uninstall ruflo-* plugins with /plugin, and check CLAUDE.md and .claude/settings.json by hand.

Verdict

Ruflo deserves its stars as a phenomenon, not as a finished product. It is a huge, sincere experiment in what a harness around Claude Code could be, and since the spring audits it has become unusually open about which parts are real — fixing a fabricated benchmark, softening its speed claims and filing its own bugs every night.

But the burden of proof still sits with you. Try ruflo-core and the console as plugins, look at what they do in a scratch repo, and only then run init on code you care about — with a pinned version, ruflo cleanup --dry-run in your back pocket, and the release notes open.