Ruflo: AI Agent Framework for Claude Code
/ruflo
Ruflo is an agent meta-harness that bolts swarm coordination, persistent memory, and multi-agent federation onto Claude Code and Codex instead of replacing them. Reach for it if you already run Claude Code daily and want agents that coordinate with each other and remember past sessions; skip it if you want one well-behaved coding assistant, since the plugin surface here is large enough to slow you down before it starts helping.
Understanding Ruflo's Agent Meta-Harness
Ruflo is a meta-harness that wraps around Claude Code and Codex, set up with one `npx ruflo init` command that adds hooks, an MCP server, and an agent daemon to your project. Per the README, it layers 100+ specialized agents and swarm coordination across hierarchical, mesh, and adaptive topologies on the model you run, adds a self-learning memory layer called AgentDB, and offers optional federation for cross-machine agent work.
Core Capabilities of Ruflo
- ✓100+ agents specialized for jobs like coding, testing, security work, documentation, and architecture reviews, coordinated through hierarchical, mesh, or adaptive swarm topologies with consensus, per the README.
- ✓AgentDB, an HNSW-indexed vector memory store the README says was measured about 1.9x faster than brute-force search at N=20k and 3.2x-4.7x faster at N=5k, with recall@10 around 0.99.
- ✓SONA neural patterns and a ReasoningBank drive what the README calls self-learning: agents that draw on past task trajectories instead of starting cold every session.
- ✓12 background workers that auto-trigger for jobs like auditing and finding test gaps, according to the README.
- ✓Agent federation lets agents on different machines join a zero-trust network, authenticate with mTLS and ed25519, and exchange work through a 14-type PII detection pipeline that strips sensitive data first.
- ✓A Web UI beta at flo.ruv.io runs multi-model chat (Qwen, Claude, Gemini, OpenAI) with roughly 210 MCP tools callable in parallel, and ships as a self-hostable Docker image.
- ✓MetaHarness grades an agent setup's readiness on a 1-100 scale and flags security issues across your tool configs; its `ruflo eject` command detaches a project from Ruflo and repackages it as its own standalone toolkit.
- ✓A plugin marketplace — the README lists 35 plugins spanning memory, testing, security auditing, DevOps, and domain-specific work like IoT device management and trading.
Installing and Setting Up Ruflo
Ruflo has two install paths documented in the README, and they are not the same tool. The plugin route runs inside Claude Code: add the marketplace with `/plugin marketplace add ruvnet/ruflo`, then install what you need, e.g. `/plugin install ruflo-core@ruflo` or `/plugin install ruflo-swarm@ruflo`. That adds slash commands and agent definitions but, per the README, writes zero files to your workspace and only registers an MCP server if `ruflo-core` is among the plugins you picked. For the full loop — 30 skills, 60+ commands, and 98 agents, alongside an MCP server, hooks, and a daemon, per the README's own comparison table — run `npx ruflo@latest init wizard` for an interactive setup or `npx ruflo@latest init` for a non-interactive one; macOS, Linux, WSL, and Git-Bash users can also pipe `curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash`. This CLI path creates `.claude/`, `.claude-flow/`, and a `CLAUDE.md` in your project. To register Ruflo as a standalone MCP server instead, the README gives `claude mcp add claude-flow -- npx ruflo@latest mcp start`.
Working with Ruflo Agents and Swarms
Day to day, the README says you are not meant to poke at Ruflo's internals directly: after `npx ruflo init`, you keep using Claude Code as normal, and a hooks system takes care of routing tasks, learning from what worked, and keeping agents coordinated behind the scenes. The README notes you don't need to memorize all 314 MCP tools, nor all 26 CLI commands, just to use it day to day. Federation works differently and is explicit: `federation init` generates a keypair, `federation join wss://<peer>` connects to another team's endpoint, and `federation send --to <peer> --type task-request --message "..."` hands off a task, with PII stripped automatically before it leaves your machine. The Web UI is a separate entry point. Open flo.ruv.io, pick a model, and start chatting — no install or API key needed for the hosted demo.
Practical Applications of Ruflo
- •Running a Claude Code session that spawns its own sub-agents for pieces of a task instead of you manually splitting work across separate chats.
- •Keeping project context and past task outcomes around across sessions via AgentDB, instead of re-explaining the codebase every time you open it.
- •Sharing work between agents on separate machines or organizations through federation, with PII stripped before anything crosses the boundary.
- •Auditing an existing AI agent setup for security gaps with the MetaHarness plugin before you ship it.
- •Trying several frontier models against the same MCP toolset from one chat interface via the Web UI, with no install required.
Who is Ruflo Designed For?
Ruflo is aimed at developers already living inside Claude Code or Codex who want more than a single-session assistant: teams running multi-step agent work who need memory that survives a restart, or who want several agents working a problem at once instead of one. It also fits anyone curious about agent-to-agent collaboration across machines, since federation is a first-class feature rather than a bolt-on. It's a poor fit if you want a minimal setup — the full CLI install drops hooks, a daemon, and multiple config files into your project, and the plugin marketplace alone lists 35 plugins to sort through.
Strengths
- ✓Two install paths instead of one: try a single plugin's slash commands with zero workspace files before committing to the full CLI loop.
- ✓Memory and learning aren't an afterthought — AgentDB, SONA, and ReasoningBank are named, specific mechanisms in the README rather than a vague "remembers context" claim.
- ✓Federation ships with concrete security mechanics on paper: mTLS plus ed25519 identity, a 14-type PII pipeline, and BLOCK/REDACT/HASH/PASS policies per trust level.
- ✓MIT license, so there's no copyleft or usage restriction blocking commercial use.
- ✓The Web UI and Goal Planner are self-hostable via Docker rather than locked to the hosted demos at flo.ruv.io and goal.ruv.io.
Considerations When Using Ruflo
- △The README gives no maturity signal beyond star count — no release history, version policy, or stability guarantee for a project with this much installed surface area (30 skills, 60+ commands, and 98 agents in the CLI path alone).
- △The full CLI install is not lightweight: it writes `.claude/`, `.claude-flow/`, a `CLAUDE.md`, hooks, and a daemon into your project, more to adopt and later remove than a single dependency.
- △Some CLI examples in the README still use the `claude-flow` command name (e.g. `npx claude-flow@latest federation init`) alongside newer `npx ruflo@latest` examples elsewhere, a leftover from the project's rename from Claude Flow that can make it unclear which command is current.
- △The AgentDB speed numbers are benchmark-specific, measured at N=20k and N=5k against brute-force search, and the README itself says the approach 'ties/loses at small N,' so the speedup isn't universal.
- △Federation's trust-scoring formula and PII detection are described in the README but aren't independently verifiable from the repo facts alone, so you're trusting the project's own account until you read the code.
Comparing Ruflo with Other Agent Frameworks
Frequently Asked Questions About Ruflo
Ruflo is released under the MIT license, per its GitHub repository.
The README describes multi-provider routing across Claude, GPT, Gemini, Cohere, and Ollama, and separately the Web UI offers Qwen, Claude, Gemini, and OpenAI models via OpenRouter plus any OpenAI-compatible endpoint such as vLLM or LM Studio.
Ruflo agents can work across machines through its federation feature: they join a zero-trust network, verify each other with mTLS and ed25519, and exchange work with PII stripped before it leaves the originating machine, per the README.
Ruflo's Web UI is self-hostable. The README says it ships as a Docker image with an embedded MongoDB option, deployable to Cloud Run, Fly, Kubernetes, or docker-compose, separate from the hosted demo at flo.ruv.io.
Ruflo stores agent memory in AgentDB, an HNSW-indexed vector database, and layers SONA neural patterns and a ReasoningBank on top so agents draw on past task trajectories rather than starting fresh every session.
Ruflo includes an AIDefence plugin for prompt-injection blocking and PII detection, a security-audit plugin for CVE scanning, and a MetaHarness plugin that grades an agent setup's security readiness on a 1-100 scale, per the README.
The problem it solves
Claude Code and Codex sessions run as isolated loops: each one starts cold, forgets what happened last time, and has no built-in way to split a task across several agents or let agents on different machines compare notes without you pasting context by hand. Ruflo's README frames the project around that gap, describing itself as the harness half of "Agent = Model + Harness" — the memory, routing, and inter-agent communication layer that a model alone doesn't provide.
Related repositories
Curious whether ruflo is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about ruflo.