Ruflo: the agent meta-harness that wraps Claude Code and Codex

What Ruflo actually wraps, and who it is for

Ruflo describes itself as an agent meta-harness for Claude Code and Codex. The README's own formula is "Agent = Model + Harness": the model writes, and the harness supplies tools, memory, loops, sandboxes and controls. Ruflo is the second half of that equation. It does not ship a model. It sits between your coding agent and the work, adding a router, a swarm layer, a memory layer and a learning loop.

The audience is narrow and specific. If you already drive Claude Code or Codex from a terminal and you keep re-explaining the same project context, or you want several agents working a task in parallel, this is the layer that addresses that. The README is explicit that newcomers do not need to learn the full surface: after init, it says, you can use Claude Code normally, and the hooks system routes tasks, learns from successful patterns and coordinates agents in the background. That claim is the whole pitch, and it is also the thing to verify on your own machine, because background behavior that you did not configure is exactly the kind of behavior that is hard to audit later.

The project was previously published as claude-flow, and the package.json still carries the name claude-flow with a claude-flow binary, while the repository and the npx entry point are ruflo. That split is worth knowing before you search your lockfile for the wrong string.

Router, swarm, memory, learning loop: the architecture in the README

The README's diagram is short enough to read literally: User to Ruflo (CLI or MCP) to Router to Swarm to Agents to Memory to LLM Providers, with a Learning Loop arrow returning from Memory back to the Router. Each hop is a real component in the repository tree, not just a drawing.

The CLI and the MCP server are two front doors onto the same machinery. The CLI is the bin entry declared in package.json, with 26 commands according to the README. The MCP server is the other door, exposing 314 tools to a host that speaks the Model Context Protocol. Memory is backed by agentdb, and the repository root carries agentdb.rvf and agentdb.rvf.lock files, which is where persisted state appears to live. The learning loop is what feeds successful patterns back into routing decisions.

Federation is the part that changes the deployment picture. The Cargo workspace lists v3/crates/ruflo-federation-peer, a Rust binary, which means a full deployment can include a compiled peer process alongside the TypeScript packages. The README frames federation as letting agents on different machines collaborate without leaking data. That is a meaningful distinction from simply running the CLI on two hosts, but the README does not document the wire format or the trust model in the section available here, so treat the security properties as unverified until you read the federation plugin's own documentation.

One structural detail is worth flagging because it affects how you build from source. The Cargo.toml comments explain that v3/plugins/gastown-bridge is deliberately placed in exclude rather than members, because it declares its own nested workspace and Cargo refuses to resolve any member of a parent workspace while a listed member path is itself a workspace root. The manifest also states plainly that ruflo is primarily TypeScript and the Rust workspace exists so a repo-scorecard analyzer can see the Rust components. That is an honest note, and it tells you the Rust side is not the center of gravity.

Installing Ruflo: npx ruflo init versus the plugin marketplace

The README opens with a warning that there are two install paths with very different surface areas, and it labels them. The plugin path gives slash commands, a few skills and per-plugin agent definitions, and writes zero files into your workspace. The CLI path gives the full loop: 98 agents, 60+ commands, 30 skills, an MCP server, hooks and a daemon, and it writes .claude/, .claude-flow/, CLAUDE.md, helpers and settings into your repository.

For the plugin path, the marketplace is added first and then individual plugins are installed. According to the README, ruflo-core registers its own MCP server, and its tools are callable under prefixed names rather than the bare names the CLI scaffold uses.

/plugin marketplace add ruvnet/ruflo
/plugin install ruflo-core@ruflo
/plugin install ruflo-swarm@ruflo
/plugin install ruflo-rag-memory@ruflo

After that, the README says the tools appear as mcp__plugin_ruflo-core_ruflo__* names, for example mcp__plugin_ruflo-core_ruflo__memory_store, not memory_store or swarm_init. That naming difference is the single most common way to end up with a command that does not resolve, so check which path you installed before copying any example from elsewhere.

The CLI path is the one the README recommends for production. It is a single command, and the README states it gives Claude Code a nervous system.

npx ruflo init

What you should see afterward is a set of new dot-directories and a CLAUDE.md in your project root. The README does not document an uninstall or rollback command for the files this writes, so if you are trying it inside a repository you care about, run it on a branch or in a scratch clone first and diff the result.

The repository also carries a Cargo workspace for the federation peer and the agntcy crate, so a build that includes federation goes through cargo as well as npm. The README does not give a Windows-specific install command, and one of the recent releases is titled around Windows CI, which suggests Windows support has been an active area of fixes rather than a settled one.

Where Ruflo is the wrong choice

The clearest limitation is host lock-in. Ruflo is built around Claude Code and Codex. The README describes the harness as the execution layer around those two, and the integration points are hooks and slash commands that belong to those hosts. If your team standardizes on a different agent runtime, or you want orchestration that treats every model provider as a first-class citizen, you are working against the grain of the design rather than with it.

The second limitation is surface area. The README itself frames the plugin path as the way to "try a single plugin's commands without committing to the full install," which is an admission that the full install is a commitment. The CLI path writes configuration into your repository, installs hooks, and runs a daemon. Hooks that fire automatically and a daemon that runs in the background are not things you can reason about from a README alone. You need to read what they execute on your machine.

The third is version churn. The release history shows v3.38.19 described as superseding broken v3.38.17 and v3.38.18, with the fix list covering Windows CI, dead agentdb exports, a memory driver doctor check and MCP HTTP transport. A release that supersedes two broken ones in the same patch range is a signal about the stability of that window, and it is worth pinning a version you have verified rather than tracking the latest tag.

Finally, the README does not document rollback, and it does not document what the daemon does when it cannot reach an LLM provider. Those are gaps, not failures, but they are gaps you should close yourself before running this on a shared machine.

How Ruflo differs from a general-purpose agent framework

The obvious comparison is LangGraph, and the difference is architectural rather than cosmetic. LangGraph is a library you import into your own Python or JavaScript program: you define the graph, the nodes and the state, and your application is the thing that runs. Ruflo is the inverse. It installs into an existing host application, Claude Code or Codex, and modifies how that host behaves through hooks and an MCP server. You do not write the orchestration loop; you configure a harness that already has one.

That inverts the cost profile. With a library you pay upfront in code and get explicit control over every transition. With Ruflo you pay almost nothing upfront and inherit a router, a swarm layer and a learning loop whose decisions are made for you. The README leans into this: "You keep writing code. Ruflo handles the coordination." Whether that trade is good depends entirely on whether you want to inspect the routing decisions. If you do, a library is the better fit. If you want coordination to disappear into the background, Ruflo is aimed at exactly that.

A second comparison point is the plugin architecture itself. Ruflo ships 35 plugins split across orchestration, memory, intelligence, code quality, security and architecture, each with its own README under plugins/. That is closer to an editor extension ecosystem than to a framework: you opt into capabilities one at a time. It also means the quality of any given capability is the quality of that plugin, not of the whole project, and the README's own table is the only map of which is which.

Maintenance, licensing and the cost of staying current

The repository is not archived, and the last push was on 2026-08-24, which is recent enough that the project is being worked on rather than parked. The most recent release in the list is v3.38.20, tagged the same day, with a statusline fix described as stopping the pinning of intelligence to a hardcoded 0 percent. That is a small, specific fix, and the pattern of small frequent patch releases suggests a project that ships continuously rather than on a schedule.

Continuous patching has a cost. If you install via npx ruflo init, you are pulling whatever the current published version is at the moment you run it, and the README does not describe a version-pinning flag or a lock step for the scaffolding it writes. The practical consequence is that two engineers running init a week apart may not get identical configuration. If reproducibility matters to you, capture the generated files in version control immediately after init and treat them as your own.

The licence is MIT, which the repository states in LICENSE and the README badge confirms. MIT is permissive: it allows commercial use, modification and redistribution, and it comes with no warranty. That last clause matters here more than in a typical library, because Ruflo installs hooks and a daemon that execute on your machine. The licence does not give you any assurance about what those processes do. Nothing in this section is legal advice; if the daemon's behavior matters contractually, read the source under .claude/ and the CLI dist files rather than relying on the licence text.

Upgrade cost is dominated by the plugin count. With 35 plugins and a workspace spanning several @claude-flow packages, a version bump can move the CLI, the MCP server, the shared package and the guidance package together. The package.json files list shows those as separate workspace members with separate dist outputs, so a partial upgrade is possible and probably inadvisable.

Editorial conclusion

Adopt Ruflo if you already work inside Claude Code or Codex and want memory, hooks and multi-agent coordination without leaving the terminal; the CLI path is the one that installs hooks and the MCP server. Skip it if you want a framework-agnostic orchestrator, since the harness is built around those two hosts. Before committing, run npx ruflo init in a scratch repository and inspect the .claude/, .claude-flow/ and CLAUDE.md files it writes, because the plugin path leaves no such files and registers only the ruflo-core MCP server.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes