Ruflo has 72,000 stars, 8,500 forks and 7,440 commits. It's MIT licensed. And it's the most ambitious thing built on top of Claude Code — a layer that turns one assistant into a coordinated team with memory. It's also easy to install in a way that quietly does almost nothing, which is the part this guide is really about.
What's in this guide
1. What a "harness" actually means
The repo opens with a line worth stealing: Agent = Model + Harness.
The model writes. The harness gives it tools, memory, loops, sandboxes and controls so it can actually finish work. Claude Code is already a harness — Ruflo is a harness around that harness, which is why it calls itself a meta-harness.
Concretely, it adds four things Claude Code doesn't do alone:
- Multiple agents that coordinate rather than running in isolation — hierarchical, mesh and adaptive topologies with consensus.
- Memory that survives the session — vector storage with HNSW indexing instead of context that dies when you close the window.
- Learning from what worked — it records successful patterns and routes future tasks accordingly.
- Federation — agents on different machines collaborating without leaking data across the boundary.
The pitch in one line, theirs: "So agents don't just run, they collaborate."
2. The two install paths — and the trap
This is the thing to understand before anything else
There are two installs. They share a name and almost nothing else. The repo flags this itself, against an open issue — which tells you how often people get caught.
| Plugin install | CLI install | |
|---|---|---|
| What you get | Slash commands, some skills, agent definitions | The full loop — 98 agents, 60+ commands, 30 skills, MCP server, hooks, daemon |
| Files written | Zero | .claude/, .claude-flow/, CLAUDE.md, helpers, settings |
| Hooks | No | Yes |
| Best for | Trying one plugin | Production — "everything works as documented" |
Plugin path — inside Claude Code:
/plugin marketplace add ruvnet/ruflo/plugin install ruflo-core@rufloCLI path — in your terminal:
npx ruflo@latest init wizardWhy people get stuck. They install the plugin, follow a tutorial written for the CLI install, and nothing behaves as described. No hooks fired, no daemon, no background workers, and the MCP tool names are different — the plugin registers tools under a long prefixed name, not the short memory_store / swarm_init names the CLI scaffold uses.
Neither path is wrong. But only the CLI path gives you the thing the documentation describes. If you're evaluating Ruflo, evaluate that one.
3. Why searching for it fails
Ruflo used to be called Claude Flow. It was renamed — the repo's own explanation: "The 'Ru' is the rUv. The 'flo' is working until 3am."
The rename didn't reach everywhere, and this will bite you:
- The repo is
ruvnet/ruflo, and the npm package isruflo. - But several documented commands still use
claude-flow— including the federation examples and the MCP registration, which readsclaude mcp add claude-flow -- npx ruflo@latest mcp start. Both names, one line. - Plugin packages are published under the
@claude-flow/scope. - Some links in the README still point at the old
claude-flowrepo path.
What this means for you: searching "Claude Flow" surfaces tutorials for older versions that may not match current behaviour. Search the new name for current material — and don't assume a command is a typo just because the two names appear together. Sometimes they're both correct.
4. What you actually get
On the CLI path, the headline capabilities:
- Specialised agents — coder, tester, reviewer, architect, security, and many more.
- Swarm coordination — hierarchical, mesh and adaptive topologies, with consensus protocols.
- Vector memory — AgentDB with HNSW indexing.
- 12 background workers that trigger automatically — audit, optimise, test-gap detection.
- 27 hooks that route tasks and capture what worked.
- Multi-provider routing — Claude, GPT, Gemini, Cohere and Ollama with failover.
- Federation — mTLS and ed25519 identity, PII stripped before anything leaves your machine, and behavioural trust scoring where upgrades take history but downgrades are instant.
ruflo verify— cryptographically check your installed bytes against a signed witness. Genuinely unusual and genuinely good.
Two things free to try with no install: the web UI beta at flo.ruv.io — multi-model chat with MCP tool calling, no account or API key needed — and the goal planner at goal.ruv.io, which turns a plain-English goal into an executable agent plan. If you want to understand what this project is before committing files to your repo, start there.
5. The numbers don't agree
Not a criticism of the software — a warning about repeating its stats.
| Claim | Says one place | Says another |
|---|---|---|
| Agents | 100+ | 98 |
| Plugins | 35 | 33 native + 21 npm |
| MCP tools | 314 | ~210 |
All three pairs appear in the same README. It's a fast-moving project and the docs lag the code — but if you quote a number publicly, quote it with the caveat.
Credit where it's due, though. The memory benchmark is unusually honest: roughly 1.9× faster at 20,000 items and 3.2–4.7× at 5,000 versus brute force, with recall around 0.99 — and then it says outright that the approximate index "ties/loses at small N." Publishing the conditions under which your own benchmark stops winning is rare. Treat the headline speed claims against other frameworks — a range running from 1.3× to 1953× — with more caution, because a spread that wide means the top number is one specific scenario, not a general result.
6. Who should not install this
This is a lot of machinery, and the guides that gush about it rarely say who it's wrong for.
Skip it if:
- You're new to Claude Code. Learn the base tool first. You can't evaluate a coordination layer if you don't yet know what you're coordinating.
- Your projects are small. Swarms and vector memory solve problems that appear at scale. On a single-file script they're overhead.
- You don't want files written into your repo. The CLI install adds several directories and a
CLAUDE.md. That's how it works — but know it before, not after. - You need stability over capability. 7,440 commits is a project moving fast. Fast means features and it also means churn.
Install it if you're running real multi-step work through Claude Code, you've felt the pain of context dying between sessions, and you've wanted more than one agent working at once. That's the problem this was built for, and it addresses it more seriously than anything else in the category.
7. Where to start
- Open flo.ruv.io. Free, no signup. Fifteen minutes here tells you whether the concept is for you, and costs you nothing.
- Then the plugin path on a project you don't care about — marketplace, then
ruflo-core. Slash commands, zero files, fully reversible. - Then the CLI install, still on a throwaway project.
npx ruflo@latest init wizard. Now you're seeing the real thing. - Read the Status doc in the repo before trusting any capability claim — it's their own is-it-ready page and it's more current than the README.
- Only then put it on something that matters.
The honest summary: this is the most serious attempt anyone has made at turning Claude Code into a coordinated system rather than a single assistant, and it's free and MIT. It's also complex enough that installing it casually will mostly produce confusion. Try the hosted UI, install the plugin, then decide — in that order.
Method note: Every figure here was read off the repository and its README in August 2026 — which is how the install-path split, the three contradictory counts and the leftover claude-flow commands turned up. A project at 7,440 commits changes weekly; check the repo before relying on any of it.
Want the next one first?
The Input Daily — a 5-minute AI brief every weekday. 3 stories that matter, 1 tool worth trying, 1 prompt to steal.
Free. Every morning. Unsubscribe in one click. Privacy Policy.
You're all set.
The Input Daily lands in your inbox tomorrow morning. While you're here — the rest of the guides are free too.
Browse all free guides →