# Ruflo: An agent meta-harness for Claude Code and Codex

> Source: <https://github.com/ruvnet/ruflo>
> Published: 2026-07-25 20:12:41+00:00

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— the execution layer around Claude Code and Codex that adds 100+ specialized agents, coordinated swarms, self-learning memory, federated comms across machines, and enterprise security guardrails. So agents don't just run, they collaborate.

One `npx ruflo init`

gives Claude Code a nervous system: agents self-organize into swarms, learn from every task, remember across sessions, and — with federation — securely talk to agents on other machines without leaking data. You keep writing code. Ruflo handles the coordination.

``` php
Self-Learning / Self-Optimizing Agent Architecture

User --> Ruflo (CLI/MCP) --> Router --> Swarm --> Agents --> Memory --> LLM Providers
                          ^                           |
                          +---- Learning Loop <-------+
```

New to Ruflo?You don't need to learn 314 MCP tools or 26 CLI commands. After`init`

, just use Claude Code normally — the hooks system automatically routes tasks, learns from successful patterns, and coordinates agents in the background.

**📖 Background — where the name comes from**

Claude Flow is now Ruflo — named by

[, who loves Rust, flow states, and building things that feel inevitable. The "Ru" is the rUv. The "flo" is working until 3am. Underneath, powered by]`rUv`

[agentic architecture, running a supercharged Rust-based AI engine, embeddings, memory, and plugin system.]`Cognitum.One`

There are **two different install paths** with very different surface areas. Pick based on what you need (#1744):

Claude Code Plugin |
CLI install (`npx ruflo init` ) |
|
|---|---|---|
| What it gives you | Slash commands + a few skills + agent definitions per-plugin | Full Ruflo loop — 98 agents, 60+ commands, 30 skills, MCP server, hooks, daemon |
| Files in your workspace | Zero |
`.claude/` , `.claude-flow/` , `CLAUDE.md` , helpers, settings |
| MCP server registered | No (`memory_store` , `swarm_init` , etc. unavailable to Claude) |
Yes |
| Hooks installed | No | Yes |
| Best for | Try a single plugin's commands without committing to the full install | Production use — everything works as documented |

```
# 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
```

This adds slash commands and agent definitions only. The Ruflo MCP server is NOT registered, so `memory_store`

, `swarm_init`

, `agent_spawn`

, etc. won't be callable from Claude. For the full loop, use Path B below.

**🔌 All 35 plugins**

| Plugin | What it does |
|---|---|
ruflo-core |

**ruflo-swarm****ruflo-autopilot****ruflo-loop-workers****ruflo-workflows****ruflo-federation**| Plugin | What it does |
|---|---|
ruflo-agentdb |

**ruflo-rag-memory****ruflo-rvf****ruflo-ruvector**[— GPU-accelerated search, Graph RAG, 103 tools](https://npmjs.com/package/ruvector)`ruvector`

**ruflo-knowledge-graph**| Plugin | What it does |
|---|---|
ruflo-intelligence |

**ruflo-graph-intelligence****ruflo-daa****ruflo-ruvllm****ruflo-goals**| Plugin | What it does |
|---|---|
ruflo-testgen |

**ruflo-browser****ruflo-jujutsu****ruflo-docs**| Plugin | What it does |
|---|---|
ruflo-security-audit |

**ruflo-aidefence**| Plugin | What it does |
|---|---|
ruflo-adr |

**ruflo-ddd****ruflo-sparc****ruflo-metaharness**[guide](/ruvnet/ruflo/blob/main/docs/metaharness-user-guide.md))** ruflo-arena**| Plugin | What it does |
|---|---|
ruflo-migrations |

**ruflo-observability****ruflo-cost-tracker**| Plugin | What it does |
|---|---|
ruflo-agent |

**ruflo-plugin-creator**| Plugin | What it does |
|---|---|
ruflo-iot-cognitum |

**ruflo-neural-trader**[— AI trading with 4 agents, backtesting, 112+ tools](https://npmjs.com/package/neural-trader)`neural-trader`

**ruflo-market-data****macOS / Linux / WSL / Git-Bash:**

```
# One-line install (POSIX shells only — see Windows note below)
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash
```

**All platforms (including native Windows PowerShell / cmd):**

```
# Interactive setup wizard — runs identically on every platform
npx ruflo@latest init wizard

# Quick non-interactive init
# npx ruflo@latest init

# Or install globally
npm install -g ruflo@latest
```

💡

Windows users:the`curl ... | bash`

form needs a POSIX shell (Git-Bash, WSL, MSYS). The`npx ruflo@latest init wizard`

line works natively in PowerShell and cmd. If you hit an`'bash' is not recognized`

error, use the`npx`

line instead — both end up running the same init flow.

```
# Add Ruflo as an MCP server in Claude Code (canonical form, matches USERGUIDE.md)
claude mcp add ruflo -- npx ruflo@latest mcp start
```

| Capability | Description |
|---|---|
🤖 100+ Agents |
Specialized agents for coding, testing, security, docs, architecture |
📡 Comms Layer |
Zero-trust federation — agents across machines/orgs discover, authenticate, and exchange work securely |
🐝 Swarm Coordination |
Hierarchical, mesh, and adaptive topologies with consensus |
🧠 Self-Learning |
SONA neural patterns, ReasoningBank, trajectory learning |
💾 Vector Memory |
HNSW-indexed AgentDB — measured ~1.9x faster at N=20k, ~3.2x–4.7x at N=5k vs brute force (recall@10 ~0.99); ANN wins above the crossover, ties/loses at small N. See
`scripts/benchmark-intelligence.mjs` |

**Background Workers****Plugin Marketplace****Multi-Provider****Security****Agent Federation**[MetaHarness](/ruvnet/ruflo/blob/main/docs/metaharness-user-guide.md)`ruflo eject`

turns a ruflo project into a standalone agent toolkit with its own name. [Full guide](/ruvnet/ruflo/blob/main/docs/metaharness-user-guide.md).[Web UI Beta](https://flo.ruv.io/)[RuFlo Research](https://goal.ruv.io/)[/agents](https://goal.ruv.io/agents)### Web UI (Beta) — self-hostable, hosted demo at [flo.ruv.io](https://flo.ruv.io/)

**RuFlo's web UI is a multi-model AI chat with built-in Model Context Protocol (MCP) tool calling.** Talk to Qwen, Claude, Gemini, or OpenAI while RuFlo invokes the same MCP tools the CLI uses — agent orchestration, persistent memory, swarm coordination, code review, GitHub ops — directly from chat. No install, no API key needed to try it.

| What it is | Why it matters | |
|---|---|---|
| 🧠 | Any model, local or remote |
6 curated frontier models out-of-the-box — Qwen 3.6 Max (default), Claude Sonnet 4.6, Claude Haiku 4.5, Gemini 2.5 Pro, Gemini 2.5 Flash, OpenAI — via OpenRouter. Add your own: any OpenAI-compatible endpoint (vLLM, Ollama, LM Studio, Together, Groq, self-hosted). |
| 🦾 | ruvLLM self-learning AI |
Native support for
`ruvnet/RuVector/examples/ruvLLM` ) — RuFlo's self-improving local model layer. Routes to MicroLoRA adapters, learns from your trajectories via SONA, and stays on your machine. Pair with the cloud models or run fully offline. |

**~210 tools, ready to call****Bring your own MCP servers****MCP (n)** pill in the chat input →*Add Server*and paste any MCP endpoint (HTTP, SSE, or stdio). Your tools join RuFlo's native ones in the same parallel-execution flow. Run a local MCP server on`localhost:3000`

and it just works.**Tools run in parallel*** Step 1 — 2 tools completed*badge so you can see exactly what ran.**Memory that sticks***"remember my favorite color is indigo"*and ask weeks later — RuFlo recalls it. Backed by AgentDB + HNSW vector search (measured ~1.9x–4.7x faster than brute force above the crossover, recall@10 ~0.99).**Built-in capabilities tour****Self-hostable**`ruflo/src/ruvocal/Dockerfile`

) with embedded Mongo. Deploy to your own Cloud Run / Fly / Kubernetes / docker-compose. The hosted [flo.ruv.io](https://flo.ruv.io/)demo is one option; running your own is fully supported.**Zero install to try****Try the hosted demo:** [https://flo.ruv.io/](https://flo.ruv.io/) — no account, no API key. **Run your own:** the source lives in [ ruflo/src/ruvocal/](/ruvnet/ruflo/blob/main/ruflo/src/ruvocal) with a multi-stage Dockerfile (

`INCLUDE_DB=true`

builds in MongoDB) and a `cloudbuild.yaml`

for Google Cloud Run. See [ADR-033](/ruvnet/ruflo/blob/main/ruflo/docs/adr/ADR-033-RUVOCAL-WASM-MCP-INTEGRATION.md)for the architecture and

[issue #1689](https://github.com/ruvnet/ruflo/issues/1689)for the roadmap.

### Goal Planner UI — autonomous agents at [goal.ruv.io](https://goal.ruv.io/)

**Turn high-level goals into executable agent plans.** `goal.ruv.io`

is RuFlo's hosted Goal-Oriented Action Planning (GOAP) front-end — describe an outcome in plain English and watch RuFlo decompose it into preconditions, actions, and an A* path through state space, then dispatch the work to live agents at [ /agents](https://goal.ruv.io/agents).

| What it is | Why it matters | |
|---|---|---|
| 🎯 | Plain-English goals |
Type "ship the auth refactor with tests and a PR" — RuFlo extracts the success criteria, the constraints, and the implicit preconditions. No JSON, no DSL. |
| 🧭 | GOAP A* planner |
Classic gaming-AI planning ported to software work: state-space search through actions with preconditions/effects to find the shortest viable path. Replans on the fly when state changes. |
| 🤖 | Live agent dashboard |
|

**Visual plan tree*** exactly*why an agent picked a path — no opaque chain-of-thought.**Adaptive replanning****Shared memory + SONA****Wired to MCP tools****Zero install to try**[goal.ruv.io](https://goal.ruv.io/), describe a goal, watch it run. Source lives in[— Vite + Supabase, self-hostable.](/ruvnet/ruflo/blob/main/v3/goal_ui)`v3/goal_ui/`

**Try it:** [https://goal.ruv.io/](https://goal.ruv.io/) for goals · [https://goal.ruv.io/agents](https://goal.ruv.io/agents) for live agents. **Run your own:** clone the `goal`

branch and `cd v3/goal_ui && npm install && npm run dev`

.

``` php
Your Agent --> [ Remove secrets ] --> [ Sign message ] --> [ Encrypted channel ]
                 Emails, SSNs,        Proves it came       No one reads it
                 keys stripped         from you              in transit
                                                                |
                                                                v
Their Agent <-- [ Block attacks ] <-- [ Check identity ] <------+
                 Stops prompt          Rejects forgeries
                 injection

                          Audit trail on both sides.
                  Trust builds over time. Bad behavior = instant downgrade.
```

Slack gave teams channels. Federation gives agents the same thing — **shared workspaces across trust boundaries**, where agents on different machines, orgs, or cloud regions can discover each other, prove who they are, and collaborate on tasks.

The difference: some channels are trusted, some aren't. [ @claude-flow/plugin-agent-federation](https://github.com/ruvnet/ruflo/issues/1669) handles that automatically. Your agents join a federation, get verified via mTLS + ed25519, and start exchanging work — with PII stripped before anything leaves your node and every message auditable. Untrusted agents can still participate at lower privilege: they see discovery info, not your memory. As they prove reliable, trust upgrades. If they misbehave, they get downgraded instantly — no human in the loop required.

You don't configure handshakes or manage certificates. You `federation init`

, `federation join`

, and your agents start talking. The protocol handles identity, the PII pipeline handles data safety, and the audit trail handles compliance.

📘 Full user guide:[— setup, MCP tools, trust levels, circuit breaker, and the (opt-in) WireGuard mesh layer that ties packet-layer reachability to federation trust. ADR-111 deep-dive at]`docs/federation/`

[.]`docs/federation/phase7-mesh-bringup.md`

**Federation capabilities**

| Capability | How it works | |
|---|---|---|
| 🔒 | Zero-trust federation |
Remote agents start untrusted. Identity proven via mTLS + ed25519 challenge-response. No API keys, no shared secrets. |
| 🛡️ | PII-gated data flow |
14-type detection pipeline scans every outbound message. Per-trust-level policies: BLOCK, REDACT, HASH, or PASS. Adaptive calibration reduces false positives. |
| 📊 | Behavioral trust scoring |
Formula (`0.4×success + 0.2×uptime + 0.2×threat + 0.2×integrity` ) continuously evaluates peers. Upgrades require history; downgrades are instant. |
| 📋 | Compliance built-in |
HIPAA, SOC2, GDPR audit trails as compliance modes. Every federation event produces a structured record searchable via HNSW. |
| 🤝 | 9 MCP tools + 10 CLI commands |
Full lifecycle: `federation_init` , `federation_send` , `federation_trust` , `federation_audit` , and more. |

**Example: two teams sharing fraud signals without sharing customer data**

```
# 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
```

See [issue #1669](https://github.com/ruvnet/ruflo/issues/1669) for the complete architecture, trust model, and implementation roadmap.

```
# Claude Code plugin
/plugin install ruflo-federation@ruflo

# Or via CLI
npx claude-flow@latest plugins install @claude-flow/plugin-agent-federation
```

**Claude Code: With vs Without Ruflo**

| Capability | Claude Code Alone | + Ruflo |
|---|---|---|
| Agent Collaboration | Isolated, no shared context | Swarms with shared memory and consensus |
| Coordination | Manual orchestration | Queen-led hierarchy (Raft, Byzantine, Gossip) |
| Memory | Session-only | HNSW vector memory with sub-ms retrieval |
| Learning | Static behavior | SONA self-learning with pattern matching |
| Task Routing | You decide | Intelligent routing (89% accuracy) |
| Background Workers | None | 12 auto-triggered workers |
| LLM Providers | Anthropic only | 5 providers with failover |
| Security | Standard | CVE-hardened with AIDefence |

**Architecture overview**

``` php
User --> Claude Code / CLI
          |
          v
    Orchestration Layer
    (MCP Server, Router, 27 Hooks)
          |
          v
    Swarm Coordination
    (Queen, Topology, Consensus)
          |
          v
    100+ Specialized Agents
    (coder, tester, reviewer, architect, security...)
          |
          v
    Memory & Learning
    (AgentDB, HNSW, SONA, ReasoningBank)
          |
          v
    LLM Providers
    (Claude, GPT, Gemini, Cohere, Ollama)
```

Four docs for four audiences:

| Doc | When to read it |
|---|---|
|
See what currently works — capability counts, test baselines, recent fixes, what's next. The is-it-ready doc. |
|
Daily reference — every command, every config flag, every plugin. The how-do-I doc. |
|
How to grade your agent setup, scan tool configs for security, detect changes between runs, and eject a project into a standalone agent toolkit. The audit-my-setup doc. |
|
v3.8.0 SOTA matrix vs LangGraph / AutoGen / CrewAI on darwin-arm64 + linux-x64. ruflo wins cold start, single turn, RSS by 1.3×–1953×. The is-it-fast doc. |
|
Cryptographically prove your installed bytes match the signed witness — `ruflo verify` . The trust-but-verify doc. |
|
Before-merge gates, dual-mode handoff, memory namespace sharing, and witness manifest entry per merge. The safer-team-workflows doc. |

Benchmark internals (for reproduction): [ sota-workload-spec.md](https://github.com/ruvnet/ruflo/blob/perf/sota-comparator-benchmarks/docs/benchmarks/sota-workload-spec.md) ·

[·](https://github.com/ruvnet/ruflo/blob/perf/sota-comparator-benchmarks/docs/benchmarks/SOTA-PROGRESS.md)

`SOTA-PROGRESS.md`

[raw matrix JSON: darwin](https://github.com/ruvnet/ruflo/blob/perf/sota-comparator-benchmarks/docs/benchmarks/sota-matrix.json)·

[linux](https://github.com/ruvnet/ruflo/blob/perf/sota-comparator-benchmarks/docs/benchmarks/sota-matrix-linux.json)

User Guide section index:

| Section | Topics |
|---|---|
|

[Core Features](/ruvnet/ruflo/blob/main/docs/USERGUIDE.md#-core-features)[Intelligence & Learning](/ruvnet/ruflo/blob/main/docs/USERGUIDE.md#-intelligence--learning)[Swarm & Coordination](/ruvnet/ruflo/blob/main/docs/USERGUIDE.md#-swarm--coordination)[Security](/ruvnet/ruflo/blob/main/docs/USERGUIDE.md#%EF%B8%8F-security)[Ecosystem](/ruvnet/ruflo/blob/main/docs/USERGUIDE.md#-ecosystem--integrations)[Configuration](/ruvnet/ruflo/blob/main/docs/USERGUIDE.md#%EF%B8%8F-configuration--reference)[Plugin Marketplace](https://ruvnet.github.io/ruflo)| Resource | Link |
|---|---|
| Documentation |
|

[GitHub Issues](https://github.com/ruvnet/claude-flow/issues)[ruv.io](https://ruv.io)[Agentics Foundation Discord](https://discord.com/invite/dfxmpwkG2D)[Cognitum.one](https://cognitum.one)MIT - [RuvNet](https://github.com/ruvnet)