Ruflo: the 80,000-star agent harness, installed and verified — swarms, local memory, and an MCP server you can actually run

Every coding agent you have used is a model with a prompt. Ruflo is the part around it: the harness that coordinates swarms, remembers decisions, and keeps a record of what ran. It has about 80,000 GitHub stars, it is MIT-licensed, and — unusually for a project this size — the core of it can be installed and verified without an API key. This guide does exactly that, and marks clearly where the keyless path ends.

• Who: Ruflo (ruvnet/ruflo on GitHub), formerly Claude Flow — 79,901 stars, MIT license, first committed June 2025.
• What: an agent meta-harness: project scaffold (102 files), local vector memory, 379-tool MCP server, and a terminal console — verified here end to end.
• When: version verified in this guide is ruflo 3.63.7, installed and run October 28, 2026; star and tool counts are dated the same day.
• Requirement: Node.js 20 or later and a few gigabytes of free disk for the first download. No API key for Steps 1–6; a Claude Code or Codex account only for agent execution in Step 7.

Why this is blowing up now

Ruflo is the agent harness formerly known as Claude Flow. It was first committed in June 2025 by Reuven Cohen (rUv), and it has grown since into one of the most-starred agent projects on GitHub: 79,901 stars, 9,951 commits, and 5,427 forks on the repository page at the time of writing, under the MIT license. A weekly trending digest for October 19–24 measured it gaining about 564 stars a day. That is not a new model or a new chatbot. It is something duller and more useful: the workbench around the model.

Ruflo's own framing is "Agent = Model + Harness." The model writes; the harness gives it tools, memory, loops, sandboxes, and controls so it can actually work. In practice that means a command-line tool that scaffolds a project with agent definitions, skills, commands, and hooks; a memory layer that stores project decisions as vectors you can search; a terminal console for watching swarms, costs, and missions; and an MCP server that exposes the whole surface — measured here at 379 tools — to Claude Code, Codex, or any MCP-capable client. If you already run Claude Code or Codex and you have felt the gap between "the model can do this" and "the model did this, repeatably, with a record," that gap is what Ruflo sells itself as filling.

One boundary first, because it decides whether this tutorial is for you. Everything verified below runs without an API key: the install, the project scaffold, local vector memory, the MCP server's tool list, and the terminal console. Actually sending agents off to write code still needs Claude Code (version 2.1.287 or later) or Codex, plus whatever model subscription that host requires. This guide verifies the harness, not a free coding agent — and it says so wherever that distinction matters, instead of letting you discover it at the last step.

What you'll need

• Node.js 20 or later and npm, so npx works. This guide ran on Node v24.22.1 with npm 10.9.4.
• A terminal and a scratch directory. Do not run the scaffold step inside a repository you care about until you have seen what it creates: 102 files.
• A few gigabytes of free disk for the first download. The first npx invocation here pulled a large package tree (about 1.6 GB in this sandbox's npm cache) and took several minutes behind a slow proxy; later invocations started in seconds. On a normal connection it will be faster, but it is not a small install, and you should not start it on a nearly full disk.
• No API key, no account, and no GPU for Steps 1–6. A Claude Code or Codex account is only needed for the optional final step, where agents actually run.
• Git is useful for the projects you will point the harness at, but the scaffold itself does not require a repository.

Step 1: Pin the real version

Start by asking the package for its version, through npx so nothing is installed globally yet:

npx -y ruflo@latest --version

Expected output, verified October 28, 2026:

ruflo v3.63.7

Pin that number in your head, because Ruflo's documentation drifts from its releases. The README describes 314 MCP tools; the server measured in Step 5 exposes 379. The README also describes a version 2 lineage and a version 3 runtime in the same breath. When this guide quotes a number, it is the number the installed tool printed, not the number the docs promised. If your version prints something newer, the commands below should still work, but re-check any count before quoting it.

Next, look at the command surface before you install anything into a project:

npx -y ruflo@latest --help

You will see primary commands (init, start, status, agent, swarm, memory, task, session, mcp, hooks), advanced commands (neural, security, policy, performance, embeddings, hive-mind), and utility commands (config, doctor, daemon, workflow, cleanup). You only need four of them for this guide: init, status, memory, and mcp, plus the standalone console. Resist the urge to run swarm init or start yet — those are the steps that need a model host, and they are not needed to prove the harness works.

Step 2: Scaffold a project and read what it created

Make a scratch project and initialize Ruflo inside it, non-interactively:

mkdir ruflo-demo && cd ruflo-demo
npx ruflo@latest init

Expected output (abridged):

Initializing RuFlo V3
Transformers.js loaded: Xenova/all-MiniLM-L6-v2
RuFlo V3 initialized successfully!

+-------- Summary --------+
| Directories: 12 created |
| Files: 102 created      |
+-------------------------+

+---------- Claude Code Integration -----------+
| CLAUDE.md:   Swarm guidance & configuration  |
| Settings:    .claude/settings.json           |
| Skills:      .claude/skills/ (21 skills)     |
| Commands:    .claude/commands/ (16 commands) |
| Agents:      .claude/agents/ (17 agents)     |
| Helpers:     .claude/helpers/                |
| MCP:         .mcp.json                       |
+----------------------------------------------+

+------------- V3 Runtime --------------+
| Config:      .claude-flow/config.yaml |
| Data:        .claude-flow/data/       |
| Logs:        .claude-flow/logs/       |
| Sessions:    .claude-flow/sessions/   |
+---------------------------------------+

[INFO] Hooks: 7 hook types enabled in settings.json

Two things in that output deserve attention. First, the scaffold is not a thin config file. Alongside the Claude Code surface it writes a .codex/ surface, an AGENTS.md, a .claude-flow/ runtime tree, a .swarm/ directory with SQLite databases, and a ruvector.db. That is the harness's whole nervous system, and it is why you scaffold in a scratch directory first: run git status in a real repository before and after, and read .claude/settings.json to see the seven hook types it enables. Hooks run when your coding agent acts; you should know what they are before they run in a project you ship from.

Second, the line about Transformers.js is the local embedding model being loaded: Xenova's all-MiniLM-L6-v2. Ruflo downloads it on first use so that memory search (Step 4) works without calling any hosted embedding API. That download is part of why the first init is slow. One honest quirk from this run: in the sandbox, the CLI printed its success message but did not return to the prompt promptly, and the process had to be ended after the files were confirmed on disk. If the same happens to you, check that the files above exist before assuming the step failed — a success message plus 102 files is a completed scaffold, whatever the terminal does next.

Step 3: Check the system state before you trust it

Run the status command inside the scaffolded project:

npx -y ruflo@latest status

Expected output (abridged):

RuFlo V3 [STOPPED]

Swarm
[INFO]   Swarm not running

Agents
+--------+-------+
| Status | Count |
+--------+-------+
| Active |     0 |
| Idle   |     0 |
| Total  |     0 |
+--------+-------+

Memory
+----------------+--------+
| Property       |  Value |
+----------------+--------+
| Backend        |   none |
| Entries        |      0 |
| Size           |    0 B |
+----------------+--------+

STOPPED here is the correct state, not an error. No swarm is running, no daemon is running, and memory is empty — because you have not started anything or stored anything yet. The value of this step is a baseline: if a later step misbehaves, you can come back here and see whether the system state actually changed, instead of guessing. Note the memory backend reading "none" at this point; the local store in the next step is created by the memory commands themselves, and the status table does not yet reflect it.

Step 4: Store a decision and retrieve it by meaning, not keyword

This is the step that proves the harness does something useful with no model subscription at all. Store a real project decision — the kind of thing that normally lives in someone's head and is lost when they leave:

npx -y ruflo@latest memory store -k "auth-pattern" \
  -v "Use short-lived JWT access tokens with refresh-token rotation; never store passwords in localStorage"

Expected output (abridged):

+------------+--------------------------------+
| Key        | auth-pattern                 |
| Namespace  | default                      |
| Size       | 100 bytes                    |
| Vector     | Yes (384-dim)                |
| ID         | entry_1793201122890_...       |
+------------+--------------------------------+
[OK] Data stored successfully
[DEBUG] Completed in 1233ms

The "384-dim" line is the proof that this is vector memory, not a notes file: the text was embedded locally into a 384-dimensional vector by the MiniLM model from Step 2. Now retrieve it with a question phrased differently from the stored text, so a keyword search would not trivially match:

npx -y ruflo@latest memory search -q "how do we handle login tokens"

Expected output (abridged):

[INFO] Searching: "how do we handle login tokens" (semantic)
Transformers.js loaded: Xenova/all-MiniLM-L6-v2
  Search time: 15ms

+--------------+-------+-----------+-------------------------------------+
| Key          | Score | Namespace | Preview                             |
+--------------+-------+-----------+-------------------------------------+
| auth-pattern |  0.42 | default   | Use short-lived JWT access token... |
+--------------+-------+-----------+-------------------------------------+

[INFO] Found 1 results

The query shares almost no words with the stored decision — "login tokens" versus "JWT access tokens" — and it still came back first, in 15 milliseconds, with a similarity score of 0.42. That score is not high in absolute terms; it is the correct answer among one entry, and you should read it that way. With a hundred entries, the ranking matters more than any single score, and you would tune by adding entries, not by trusting the number. Confirm the store's shape with:

npx -y ruflo@latest memory stats

Expected output (abridged): provider Xenova/all-MiniLM-L6-v2, 384 dimensions, semantic search yes, HNSW index not active. That last line is worth keeping in mind when you read the README's performance claims — HNSW indexing, quoted at large speedups over brute force, was not active in this run, and search here ran over a tiny store. It worked; it was not benchmarked.

One caveat the tool itself surfaces, and you should not ignore it: search warns that entries in .swarm/agentdb-memory.db — the store written by the MCP/AgentDB path — were not searched, and that the CLI store and the AgentDB store are separate. In other words, Ruflo currently has two memory stores that do not fully see each other: the one the CLI commands write, and the one the MCP server writes. The memory peek command reports which store files your current directory resolves to, with row counts, without writing anything. Use it whenever a search comes back empty and you expected a hit, before concluding the memory is gone.

Step 5: Start the MCP server and count its tools yourself

The MCP server is how Ruflo's tools reach Claude Code, Codex, or any MCP-capable client. Its stdio transport speaks newline-delimited JSON-RPC — one JSON object per line. That detail matters, because sending it HTTP-style Content-Length framing makes it wait forever; this guide's first probe did exactly that and hung. Save the following as mcp-probe.py inside your scaffolded project:

import subprocess, json
p = subprocess.Popen(["npx", "-y", "ruflo@latest", "mcp", "start"],
                     stdin=subprocess.PIPE, stdout=subprocess.PIPE,
                     stderr=subprocess.DEVNULL, text=True, bufsize=1)
def send(obj):
    p.stdin.write(json.dumps(obj) + "
"); p.stdin.flush()
send({"jsonrpc": "2.0", "id": 1, "method": "initialize",
      "params": {"protocolVersion": "2024-11-05", "capabilities": {},
                 "clientInfo": {"name": "probe", "version": "0.1"}}})
print("INIT:", p.stdout.readline()[:300])
send({"jsonrpc": "2.0", "method": "notifications/initialized"})
send({"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}})
tools = json.loads(p.stdout.readline())["result"]["tools"]
print("TOOLS_COUNT:", len(tools))
print("FIRST_TOOLS:", [t["name"] for t in tools[:20]])
p.kill()

Run it with python3 mcp-probe.py. Expected output, verified:

INIT: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05",
  "serverInfo":{"name":"ruflo","version":"3.0.0"},
  "capabilities":{"tools":{"listChanged":true},"resources":{}}}}
TOOLS_COUNT: 379
FIRST_TOOLS: ['agent_spawn', 'agent_execute', 'agent_terminate',
  'agent_status', 'agent_list', 'agent_pool', 'agent_health',
  'agent_update', 'agent_logs', 'swarm_init', 'swarm_pheromone_update',
  'swarm_pheromone_status', 'swarm_status', 'swarm_shutdown',
  'swarm_health', 'memory_store', 'memory_retrieve', 'memory_search',
  'memory_delete', 'memory_list']

379 tools is more than the README's 314 — count drift between docs and releases, again. Trust the number your server prints. The names that matter for a first project are swarm_init, agent_spawn, memory_store, and memory_search: the same memory from Step 4, reachable by an agent client. To actually wire it into a client, the README's paths are: in Claude Code, claude mcp add claude-flow -- npx ruflo@latest mcp start; in Codex or any stdio-MCP client, command npx with arguments ["-y", "ruflo@latest", "mcp", "start"]. Those two wiring commands were not run end to end here, because this sandbox has no Claude Code or Codex account — they are documented paths, not verified ones, and the article labels them as such.

Step 6: Open the console without any coding agent at all

Ruflo's terminal console also runs standalone, with no Claude Code attached. Print a single frame of it, which is the script-friendly form the README documents:

npx -y ruflo@latest tui --plain

Expected output (abridged): a tab bar reading [1 Overview] 2 Cost 3 Swarm 4 Events 5 Missions 6 AI, a "Start here" checklist showing 1 of 3 done — initialise done, start the daemon pending, start a swarm pending — and a subsystems table confirming CLI v3.63.7, memory DB 1 entry, MCP not connected in this session, and swarm not applicable because no swarm is on disk. Run it without --plain for the interactive console, with the same tabs.

Read that checklist as the project's own to-do list. The harness is installed and it remembers one decision; the daemon (background workers for audit, optimization, and consolidation) and the swarm (up to 8 agents in the console's wording) are the parts that need a model host. Nothing in Steps 1–6 pretends otherwise, and nothing you have done so far has spent a cent on model calls.

Step 7 (optional, for Claude Code owners): the plugin path

If you do have Claude Code 2.1.287 or later, the lighter path installs no project files at all — it adds slash commands and agent definitions from a marketplace:

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

Core provides the foundation tools, Console opens the agent cockpit, and Mods add routing and policy enforcement inside Claude Code. This path was not run in this guide's sandbox, which has no Claude Code installation, so treat the commands as the README documents them, and verify the marketplace listing yourself before installing. Two warnings from the README itself, repeated here because they are easy to skip: mods run with your account's permissions and are not sandboxed, so review their code before installing; and the console's Claude-control setting defaults to read plus ask, which is the setting to keep until you have a reason to raise it. A harness that can act for you deserves the same suspicion you would give any tool with your credentials.

When to use this vs alternatives

Ruflo is the right shape when you already live in Claude Code or Codex and want one harness that adds swarm coordination, persistent memory, a console, and an MCP surface without switching frameworks. It is the wrong shape when you want a Python agent framework you can import and test like ordinary code — that is LangGraph's territory, or the OpenAI Agents SDK's — and when you want the agent itself to be free, because Ruflo does not supply the model. Against its closest cousin, ECC, the difference is emphasis: ECC is a profile of skills, agents, and rules plus a scanner for your agent config, while Ruflo is an execution layer with a daemon, a swarm runtime, and a vector memory store. If your problem is "my agent's config is sloppy," start with the scanner. If your problem is "my agents forget, run unsupervised, and leave no record," start with the harness. And if your problem is "I just want one agent to answer questions from my documents," neither is the tool — a small retrieval script will beat both on setup time, and this guide's memory step is the closest Ruflo gets to that simplicity.

What this guide did not verify

• Actual multi-agent execution: no swarm was spawned and no agent wrote code, because the sandbox has no Claude Code or Codex account and no model subscription. Every agent-execution claim in this article is the project's, not a measured result.
• The Claude Code plugin path in Step 7, the daemon, federation between machines, and the ruOS desktop companion: documented, not run here.
• README performance figures (HNSW speedups, routing accuracy, vector-search recall): quoted as claims. The one measurement this guide can stand behind is its own — a 15 ms semantic search over one entry, with HNSW not active.
• Star counts and tool counts move with releases. The figures here (79,901 stars, 379 tools, version 3.63.7) are dated October 28, 2026; re-run --version and the MCP probe before quoting them elsewhere.

The takeaway

Ruflo earns its stars the unglamorous way: it installs, it scaffolds a complete project surface, it remembers a decision locally and retrieves it by meaning, it answers an MCP tool list with 379 tools, and it shows you its own unfinished checklist in a terminal console — all without an API key. What it does not do is remove the cost of the model at the center. Buy it, or rather install it, for the harness: the memory, the record-keeping, and the coordination. Do not install it expecting a free coding team. Run Steps 1–6 in a scratch directory tonight; if the scaffold's shape and the local memory feel like the missing layer in your Claude Code or Codex setup, then — and only then — connect the model host and let it run.

Sources

• Ruflo repository page (github.com/ruvnet/ruflo) — star, commit, fork, and license figures, and the Claude Flow lineage note.
• Ruflo README — the npx install paths, the plugin commands, the standalone tui --plain form, and the warning that mods run unsandboxed with the user’s account permissions.
• GitHub Trending weekly digest, October 19–24, 2026 — the +564-stars-per-day pace quoted for Ruflo’s recent rise.
• The installed CLI itself, run in this guide: ruflo v3.63.7 — every version, file count, memory score, tool count, and console line quoted here came from running it, not from documentation alone.