DiFlowrin

Posted on Sep 6 Originally published at diflowrin.com

Ruflo: Multi-Agent Swarms for Claude Code

#performance #database #security #programming

📋 What You Need Before Ruflo Can Do Anything

Node.js with npm installed, because every install path below runs through npx or npm
Claude Code or Codex already working on your machine. Ruflo is a harness around them, not a replacement for them
A terminal: PowerShell or cmd on Windows, any POSIX shell on macOS or Linux
A project folder you are comfortable letting Ruflo write configuration into (the full install adds .claude/, CLAUDE.md and helper files)

Here is what most people miss about the Ruflo agent meta-harness: they think it is another AI coding tool. It is not. Ruflo is the thing that wraps around your AI coding tool and turns it from one chatbot into a coordinated team. The project, formerly known as Claude Flow, has a one-line formula for this: Agent = Model + Harness. The model writes. The harness gives it tools, memory, loops, sandboxes and controls so it can actually work. Ruflo is the harness.

Why should you care? Because a single agent, however good the model, hits a wall fast. One context window. One session of memory. One pair of hands. Ruflo's answer is to put an execution layer around Claude Code and Codex that adds 100+ specialized agents, coordinated swarms, self-learning memory, federated communication across machines and security guardrails. So agents do not just run, they collaborate. Let us go through how it actually works, piece by piece, because the mechanism is the interesting part.

What the Ruflo Agent Meta-Harness Actually Is

The word meta-harness sounds like marketing. It is not, it is a precise description. Claude Code is already a harness: it gives a model tools and a loop. Ruflo sits one level up and orchestrates the harness itself. One npx ruflo init gives Claude Code, in the project's own words, a nervous system: agents self-organize into swarms, learn from every task, remember across sessions and, with federation, talk to agents on other machines without leaking data.

A few facts about the project itself, because they matter for trust. Ruflo is the renamed Claude Flow, built by ruvnet. The name comes from rUv (ruv.io): the "Ru" is the rUv, the "flo" is, as the README puts it, working until 3am. Underneath it runs on Cognitum.One agentic architecture with a Rust-based engine, embeddings, memory and a plugin system. The repository is TypeScript, licensed MIT, and the license file credits RuvNet.

A harness, not a competitor

Pay attention to this part, because people get it wrong constantly. Ruflo is not an alternative to Claude Code or Codex. It depends on them. It is the layer that coordinates what those tools do: routing tasks, spawning specialized agents, keeping memory, enforcing security. You keep writing code in the tool you already use. Ruflo handles the coordination in the background. Comparing Ruflo to Claude Code is like comparing a dispatch system to a truck. The relationship is the point.

Why One Agent Is Not Enough Anymore

The thing is, single-agent setups break in predictable ways. State and memory get fragmented across agents, sometimes lost entirely, and infrastructure costs creep up when you run several agents at once, a pattern ScrapingBee's write-up describes well. The time you saved not writing code by hand starts going into wiring agents together instead.

The README carries a blunt comparison table of Claude Code with and without Ruflo. Read it as the project's own claims, because that is what it is:

Collaboration: isolated agents with no shared context, versus swarms with shared memory and consensus
Coordination: manual orchestration, versus a queen-led hierarchy using Raft, Byzantine and Gossip consensus
Memory: session-only, versus HNSW vector memory with sub-millisecond retrieval
Learning: static behavior, versus SONA self-learning with pattern matching
Routing: you decide, versus intelligent routing the project states at 89% accuracy
Background work: none, versus 12 auto-triggered workers (audit, optimize, testgaps and others)
Providers: Anthropic only, versus 5 providers with failover
Security: standard, versus CVE-hardened with AIDefence

So the pitch is not "a better model". The pitch is: the model you already pay for, plus memory that persists, plus agents that specialize, plus a coordination layer that learns. Different claim entirely.

How Ruflo Works Under the Hood

The architecture is a stack, and each layer has one job. The README lays it out like this:

Orchestration layer: the MCP server, a router and 27 hooks. This is where your instructions enter the system.
Swarm coordination: a queen agent, a topology and a consensus mechanism. Hierarchical, mesh and adaptive topologies are all supported.
The agents themselves: 100+ specialized roles, coder, tester, reviewer, architect, security and so on.
Memory and learning: AgentDB, HNSW indexing, SONA and ReasoningBank.
LLM providers: Claude, GPT, Gemini, Cohere and Ollama, with smart routing between them.

On top of that sits a learning loop. The router sends work to the swarm, the agents execute, results flow into memory, and the system feeds what it learned back into future routing decisions. The README's own diagram is: User to Ruflo (CLI/MCP) to Router to Swarm to Agents to Memory to LLM Providers, with a learning loop closing the circuit back to the router.

You do not need to learn the machine to use it

Here is the part that surprised me, in a good way. After init, you just use Claude Code normally. The hooks system routes tasks, learns from successful patterns and coordinates agents in the background. The project is explicit that you do not need to learn its 314 MCP tools or 26 CLI commands to get value. Obviously you can go deeper, the tools are all there, but the default path is: install, then work as usual, and the swarm wakes up when the task calls for it.

Self-learning: SONA and ReasoningBank

Two names worth knowing. SONA is the neural pattern layer: it matches incoming tasks against patterns that worked before. ReasoningBank stores reasoning trajectories, so a strategy that succeeded on one task can be retrieved and reused by a future agent. Add trajectory learning on top and you get the practical effect: a Ruflo setup that has been on your project for a month behaves differently from a fresh one, because it carries your project's history in its memory. A plain Claude Code session starts every morning as sharp as it was on day one, which is to say, exactly as sharp and no sharper.

How to Install Ruflo (CLI, Plugins and the Windows Case)

There are two install paths and they are not the same product. Pick wrong and you will think half the features are broken. They are not broken, you installed the lite version. So read this first.

Path A: Claude Code plugins (lite)

The plugin path gives you slash commands, a few skills and agent definitions per plugin. Zero files land in your workspace. No hooks are installed, and only ruflo-core registers its own MCP server. It is for trying a single plugin without committing:

# Add the marketplace
/plugin marketplace add ruvnet/ruflo

# Install core + any plugins you need
/plugin install ruflo-core@ruflo
/plugin install ruflo-swarm@ruflo
/plugin install ruflo-rag-memory@ruflo
/plugin install ruflo-neural-trader@ruflo

ℹ️ Note: Tools from the plugin install of ruflo-core are callable under names like mcp__plugin_ruflo-core_ruflo__memory_store, not the bare memory_store or swarm_init names the CLI install uses. If a guide references the bare names, it is describing the CLI path.

Path B: the full CLI install

The CLI path is the full Ruflo loop: 98 agents, 60+ commands, 30 skills, the MCP server, hooks and the daemon. It writes .claude/, .claude-flow/, CLAUDE.md, helpers and settings into your workspace. This is the path the documentation assumes. The steps:

Open a terminal in your project folder.
Run the interactive wizard, which works identically on every platform including native Windows PowerShell and cmd: npx ruflo@latest init wizard
Or, if you want the non-interactive version: npx ruflo@latest init. For a global install: npm install -g ruflo@latest.
On macOS, Linux, WSL or Git-Bash there is also a one-line installer: curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash
Register Ruflo as an MCP server in Claude Code: claude mcp add claude-flow -- npx ruflo@latest mcp start

⚠️ Warning: The curl ... | bash form needs a POSIX shell (Git-Bash, WSL, MSYS). On native Windows it fails with 'bash' is not recognized. Use the wizard line from step 2 instead; both end up running the same init flow.

The Ruflo Plugin Marketplace for Testing, Security and Architecture

The plugin system is where Ruflo stops being one product and becomes a platform. The README's own index lists 35 plugins, grouped by job. A quick tour of the ones that matter most:

Orchestration: ruflo-core (server, health checks, plugin discovery), ruflo-swarm (coordinate agents as a team), ruflo-autopilot (agents running autonomously in a loop), ruflo-loop-workers (background tasks on a timer), ruflo-workflows (reusable multi-step templates)
Memory and knowledge: ruflo-agentdb (fast vector database for agent memory), ruflo-rag-memory (hybrid search, graph hops, diversity ranking), ruflo-rvf (save and restore memory across sessions), ruflo-ruvector (GPU-accelerated search and Graph RAG with 103 tools), ruflo-knowledge-graph
Intelligence: ruflo-intelligence (agents learn from past successes), ruflo-ruvllm (run local LLMs like Ollama with smart routing), ruflo-goals (break big goals into plans), ruflo-daa
Code quality: ruflo-testgen (find missing tests and generate them), ruflo-browser (browser testing with Playwright), ruflo-jujutsu (analyze git diffs, score risk, suggest reviewers), ruflo-docs
Security: ruflo-security-audit (scan for vulnerabilities and CVEs), ruflo-aidefence (block prompt injection, detect PII, safety scanning)
Architecture and methodology: ruflo-adr (living architecture decision records), ruflo-ddd (scaffold domain-driven design: contexts, aggregates, events), ruflo-sparc (a guided 5-phase development methodology with quality gates), ruflo-metaharness, ruflo-arena (pit agent strategies against each other in tournaments)
DevOps: ruflo-migrations, ruflo-observability (structured logs, traces, metrics), ruflo-cost-tracker (token usage, budgets, cost alerts)
Domain-specific: ruflo-neural-trader (AI trading with 4 agents, backtesting, 112+ tools), ruflo-market-data, ruflo-iot-cognitum

One honesty note on numbers. The plugin index in the README lists 35 plugins, while the capability table in the same README describes the marketplace as 33 native Claude Code plugins plus 21 npm plugins. Both figures come from the project itself, just from different groupings, so do not try to reconcile them into one magic number. The point stands either way: there is a lot, and it is modular.

Ruflo AgentDB: HNSW Vector Memory Performance, Measured Honestly

Memory is where Ruflo either proves itself or does not, so let us look at actual numbers. AgentDB is the built-in vector store, indexed with HNSW (Hierarchical Navigable Small World, a graph index for approximate nearest-neighbor search). This is what gives agents persistent RAG memory across sessions: they retain context, learn from previous runs and share knowledge through semantic search.

The repository's own audit reports measured figures, and they are specific: about 1.9x faster than brute force at N=20k, and about 3.2x to 4.7x faster at N=5k, with recall@10 around 0.99. And here is the part I respect: the same audit admits the approximate index ties or loses at small N, and only wins above the crossover point. The project publishes both the audit document and the benchmark script (scripts/benchmark-intelligence.mjs) so you can reproduce the numbers yourself.

About those bigger claims you will see elsewhere

Third-party coverage quotes far more aggressive figures. One comparison, AI Success Lab, states HNSW search "up to 12,500 times faster than standard vector lookups". The project's own measured audit says 1.9x to 4.7x against brute force with near-perfect recall. These are not the same claim and they are not measured the same way, so do not average them in your head: the conservative, reproducible number is the one in the repo, and the five-digit one is a blog's framing. When a vendor and a fan disagree about the vendor's product, believe the vendor's benchmark script, because you can run it.

On the cost side, Bright Data's write-up reports that Ruflo's multi-tier routing (WASM plus LLMs) cuts API costs by up to roughly 75%, and that a default local setup exposes 118 Ruflo skills inside Claude Code. Treat those as that publication's reported figures, not as guarantees for your workload. Your mileage depends on which tasks route to WASM and which need a frontier model.

Using Ruflo Federation for Zero-Trust Multi-Agent Collaboration

Now the part that sounds like science fiction and is actually plumbing. Federation lets agents on different machines, different organizations, different cloud regions discover each other, prove who they are and exchange work. The README calls it Slack for agents, and the analogy holds: shared workspaces across trust boundaries, except some channels are trusted and some are not, and the system handles the difference automatically.

The pipeline, step by step:

Before anything leaves your node, a PII pipeline scans the outbound message. It is a 14-type detection system, and per trust level it can BLOCK, REDACT, HASH or PASS each finding. Emails, keys, personal data: stripped before transit.
The message is signed. Identity is proven with mTLS plus ed25519 challenge-response. No API keys, no shared secrets.
The message travels over an encrypted channel. Nobody reads it in transit.
On the receiving side, identity is checked (forgeries rejected) and prompt injection attempts are blocked.
Both sides write an audit trail. Every federation event produces a structured, searchable record, with HIPAA, SOC2 and GDPR audit trails available as compliance modes.

Trust is behavioral, not binary. The scoring formula is published: 0.4 × success + 0.2 × uptime + 0.2 × threat + 0.2 × integrity. New agents start untrusted and see discovery info only, not your memory. Upgrades require history. Downgrades are instant, no human in the loop. See the design? Misbehave once and you are demoted on the spot; earn your way up slowly. That is what zero-trust means here in practice.

The lifecycle is exposed through 9 MCP tools and 10 CLI commands. The README's example (note it invokes the claude-flow package name, the project's former identity, which the commands still use):

# Team A: initialize federation and generate keypair
npx claude-flow@latest federation init

# Team A: join Team B's federation endpoint
npx claude-flow@latest federation join wss://team-b.example.com:8443

# Team A: send a task — PII is stripped automatically before it leaves
npx claude-flow@latest federation send --to team-b --type task-request \
  --message "Analyze transaction patterns for account anomalies"

# Team A: check peer trust levels and session health
npx claude-flow@latest federation status

💡 Tip: The worked example in the docs is two teams sharing fraud signals without sharing customer data. The PII stripping is what makes that sentence possible instead of a compliance incident. There is also an opt-in WireGuard mesh layer documented under docs/federation/ if you need packet-layer reachability tied to federation trust.

The Web UI and the GOAP A* Planner at goal.ruv.io

Two hosted front-ends ship with the project, and both are self-hostable. They are worth knowing about even if you live in the terminal, because they show what the harness can do when you drive it from a chat window or a goal statement.

flo.ruv.io: multi-model chat with MCP tool calling

The web UI is a multi-model AI chat with built-in Model Context Protocol (MCP) tool calling. Six curated frontier models come out of the box: Qwen 3.6 Max (the default), Claude Sonnet 4.6, Claude Haiku 4.5, Gemini 2.5 Pro, Gemini 2.5 Flash and OpenAI, all via OpenRouter. You can add any OpenAI-compatible endpoint: vLLM, Ollama, LM Studio, Together, Groq, self-hosted. There is native support for ruvLLM, the project's self-improving local model layer (it lives in ruvnet/RuVector/examples/ruvLLM), which routes to MicroLoRA adapters and learns from your trajectories via SONA, fully offline if you want.

The tool story is the interesting bit. About 210 tools are ready to call, in 5 server groups (Core, Intelligence, Agents, Memory, DevTools), plus an 18-tool gallery that runs entirely in your browser via WASM and works offline. One model response can fire 4 to 6 or more tools in parallel, shown as cards so you can see exactly what ran. You can also paste in your own MCP servers (HTTP, SSE or stdio) and they join the same flow. Memory is backed by AgentDB plus HNSW, so "remember my favorite color is indigo" actually survives for weeks. Self-hosting is a first-class option: the source lives in ruflo/src/ruvocal/ with a multi-stage Dockerfile (INCLUDE_DB=true builds in MongoDB) and a cloudbuild.yaml for Google Cloud Run.

goal.ruv.io: plain English in, executable plan out

The second front-end is a GOAP (Goal-Oriented Action Planning) planner. You type something like "ship the auth refactor with tests and a PR", and the system extracts success criteria, constraints and implicit preconditions, then runs an A* search through the state space to find the shortest viable path of actions. This is classic game-AI planning ported to software work.

Three details make it more than a demo. First, adaptive replanning: when an action fails or new information arrives, the planner re-runs A* from the current state instead of starting over. Second, the live dashboard at /agents shows every spawned agent with role, current step, memory namespace, token budget and status, and you can kill runaway workers or reassign tasks. Third, every action node maps to a real tool call, Ruflo's MCP tools, your custom servers or shell, scheduled in parallel where the dependency graph allows. Plans, trajectories and outcomes flow back into AgentDB, so future plans retrieve past solutions. The planner gets smarter with every run. The source is in v3/goal_ui/ (Vite plus Supabase), and you can run your own with cd v3/goal_ui && npm install && npm run dev from the goal branch.

What Ruflo Claims About Speed, and How to Check It

The project publishes a benchmark matrix comparing itself to LangGraph, AutoGen and CrewAI on darwin-arm64 and linux-x64, and it claims wins on cold start, single turn and RSS by margins from 1.3x up to 1953x. Now, pay attention to how you read that. These are the project's own numbers, run on the project's own workload spec. To its credit, the repo links the workload specification, the progress log and the raw matrix JSON for both platforms, so the claim is auditable rather than vibes. But it is still the vendor's benchmark of the vendor's product. Report it as that, run it yourself if the numbers matter to you, and do not treat the 1953x end of the range as the typical case, because ranges like that never are.

MetaHarness and ruflo verify: auditing your own setup

Two quieter tools deserve a mention. MetaHarness grades your agent setup from 1 to 100, scans tool configurations for security issues, snapshots the project so you can catch regressions between runs, and finds templates matching your repo. The ruflo eject command turns a Ruflo project into a standalone agent toolkit with its own name. Separately, ruflo verify lets you cryptographically check that your installed bytes match the signed witness manifest. For a tool whose whole job is running autonomous agents on your machine, that verify step is not a luxury.

The documentation is organized by audience, which is a small mercy: a Status doc (what currently works), a User Guide (every command and flag), the MetaHarness guide, a verification doc and a team gateway checklist for safer multi-person workflows.

When Ruflo Is the Wrong Tool

Every tool article skips this part, and every reader pays for it later. So, the honest list:

Simple, single-agent tasks. Swarm coordination has overhead. For a one-step task, plain Claude Code is faster because there is nothing to coordinate. The AI Success Lab comparison puts the crossover at roughly when a task has more than three logical steps that do not depend on each other. Below that, you are paying coordination tax for nothing.
Tiny vector workloads. The project's own audit says the HNSW index ties or loses to brute force at small N. If your agent memory is a few hundred entries, the fancy index buys you nothing.
The plugin path, if you expect the full loop. No hooks, no daemon, and most plugins do not register an MCP server. If you installed via /plugin install and the documented behavior is missing, that is why.
If you do not have the underlying tools. Ruflo is an execution layer around Claude Code and Codex. No Claude Code or Codex, nothing to harness. It also does not replace your model provider access; it routes to providers, it does not include them.

Do you see the pattern? Ruflo's costs are all coordination costs, and coordination only pays when there is something worth coordinating. One agent, one step, one session: skip it. A swarm writing, testing and reviewing across a large codebase for months: that is the case it was built for.

So, Do You Actually Need a Harness?

Back to the opening formula: Agent = Model + Harness. The industry spent two years obsessing over the model part and treating the harness as an afterthought, then wondered why agents forgot everything between sessions and could not coordinate two tasks without a human playing dispatcher. Ruflo's bet is that the harness is where the leverage was hiding all along: memory that persists, agents that specialize, coordination that learns, security that assumes nobody is trusted by default.

The project is young, the README is honest enough to publish its own audit caveats, and the install takes one npx command, so the cost of finding out whether it fits your workflow is an afternoon, not a procurement process. Try the plugin path if you are curious, the full CLI path if you are serious, and the hosted demos if you do not want to install anything at all. Anyway. Your move.

🎯 What You Now Know About Ruflo

Ruflo (formerly Claude Flow) is an agent meta-harness: an execution layer around Claude Code and Codex, not a competitor to them. Agent = Model + Harness.
One npx ruflo@latest init wizard installs the full loop on any platform, including native Windows; the plugin path is a lite version with slash commands only and no hooks.
The architecture stacks an orchestration layer (MCP server, router, 27 hooks) over swarm coordination, 100+ specialized agents, AgentDB/HNSW memory with SONA and ReasoningBank learning, and five LLM providers.
The repo's own audit measures AgentDB at roughly 1.9x to 4.7x faster than brute force with recall@10 near 0.99, and admits the index loses at small N; bigger third-party speed claims exist but are not the project's measured figures.
Federation gives zero-trust collaboration across machines: mTLS plus ed25519 identity, a 14-type PII pipeline, behavioral trust scoring and compliance-grade audit trails.
The plugin ecosystem (35 indexed plugins) covers testing, security audits, DDD and SPARC methodologies, observability and cost tracking; flo.ruv.io and goal.ruv.io add a multi-model chat UI and a GOAP A* goal planner, both self-hostable.
Ruflo is the wrong tool for simple single-step tasks: coordination overhead only pays off when work has multiple independent steps worth parallelizing.

Additional Resources

This article includes content created with AI.

DEV Community