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.

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.

<details>
<summary><strong>📖 Background — where the name comes from</strong></summary>

> Claude Flow is now Ruflo — named by [`rUv`](https://ruv.io), 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 [`Cognitum.One`](https://cognitum.one/?RuFlo) agentic architecture, running a supercharged

Rust-based AI engine, embeddings, memory, and plugin system.

</details>

---

![Ruflo Plugins](./ruflo-plugins.gif)

## Quick Start

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 | Only if `ruflo-core` is installed (it ships its own

`.mcp.json`) — most other plugins don't | 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 |

### Path A — Claude Code Plugins (lite, slash commands only)

```bash
# 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. ruflo-core (installed above) does register its own MCP server on install — its tools are callable as

mcp__plugin_ruflo-core_ruflo__* (e.g. mcp__plugin_ruflo-core_ruflo__memory_store), not the bare memory_store/swarm_init/agent_spawn names

the CLI-track scaffold uses. Other plugins generally don't ship their own MCP server. For the full loop with the CLI-track tool names, use Path B

below.

CLI Install

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.

MCP Server

# Add Ruflo as an MCP server in Claude Code
claude mcp add claude-flow -- npx ruflo@latest mcp start

What You Get

| 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 audit +

scripts/benchmark-intelligence.mjs | | ⚡ Background Workers | 12 auto-triggered workers (audit, optimize,

testgaps, etc.) | | 🧩 Plugin Marketplace | 33 native Claude Code plugins + 21 npm plugins | | 🔌 Multi-Provider | Claude, GPT, Gemini, Cohere,

Ollama with smart routing | | 🛡️ Security | AIDefence, input validation, CVE remediation, path traversal prevention | | 🌐 Agent Federation |

Cross-installation agent collaboration with zero-trust security | | 🔬 MetaHarness | Audit your AI agent setup

before you ship. Grade readiness (1-100), scan tool configs for security issues, snapshot the whole project to catch regressions over time, and find

templates that match your repo. ruflo eject turns a ruflo project into a standalone agent toolkit with its own name. [Full

guide](docs/metaharness-user-guide.md). | | 💬 Web UI Beta | Multi-model chat at flo.ruv.io with parallel MCP tool calling

and an in-browser WASM tool gallery | | 🎯 RuFlo Research | GOAP A* planner at goal.ruv.io — plain-English goals →

executable agent plans, with a live agent dashboard at /agents |

Web UI (Beta) — self-hostable, hosted demo at 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

ruvLLM (lives in 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 | 5 server groups (Core, Intelligence, Agents, Memory, DevTools) plus an 18-tool gallery that runs

entirely in your browser — works offline. | | 🔌 | Bring your own MCP servers | Click the 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 | One model response can fire 4–6+ tools at the same time. The UI shows them as

cards with a Step 1 — 2 tools completed badge so you can see exactly what ran. | | 💾 | Memory that sticks | Say *"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 | Click the question-mark icon in the sidebar — a "RuFlo Capabilities" modal opens

with the full tool list, model strengths, architecture, and keyboard shortcuts. | | 🏠 | Self-hostable | Web UI is shipped as Docker

(ruflo/src/ruvocal/Dockerfile) with embedded Mongo. Deploy to your own Cloud Run / Fly / Kubernetes / docker-compose. The hosted

flo.ruv.io demo is one option; running your own is fully supported. | | 🚀 | Zero install to try | Open the hosted URL, pick

a model, type a question. That's the whole onboarding. |

Try the hosted demo: https://flo.ruv.io/ — no account, no API key. Run your own: 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. See ADR-033 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

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.

| | 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 | goal.ruv.io/agents shows every spawned agent — role,

current step, memory namespace, token budget, status. Click in to inspect trajectories, kill runaway workers, or reassign. | | 🌳 | **Visual plan

tree | Goals render as collapsible action trees with progress, blocked branches, and rollbacks highlighted. See exactly why an agent picked a path

— no opaque chain-of-thought. | | ♻️ | Adaptive replanning | When an action fails or new info arrives, the planner re-runs A* from the current

state instead of restarting. Failures become learning, not loops. | | 🧠 | Shared memory + SONA | Plans, trajectories, and outcomes flow into

AgentDB. Future plans retrieve past solutions via HNSW — the planner gets smarter with every run. | | 🔗 | Wired to MCP tools | Every action node

maps to a tool call (RuFlo's ~210 MCP tools, your custom servers, or shell). The planner schedules them in parallel where the dependency graph allows.

| | 🚀 | Zero install to try | Open goal.ruv.io, describe a goal, watch it run. Source lives in

v3/goal_ui/ — Vite + Supabase, self-hostable. |

Try it: https://goal.ruv.io/ for goals · 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.

Agent Federation — Slack for Agents

``` 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:** [`docs/federation/`](./docs/federation/) — 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/phase7-mesh-bringup.md`](./docs/federation/phase7-mesh-bringup.md).

<details>
<summary><strong>Federation capabilities</strong></summary>

| | 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. |

</details>

<details>
<summary><strong>Example: two teams sharing fraud signals without sharing customer data</strong></summary>

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

Documentation

Four docs for four audiences:

| Doc | When to read it | |-----|-----------------| | Status | See what currently works — capability counts, test baselines,

recent fixes, what's next. The is-it-ready doc. | | User Guide | Daily reference — every command, every config flag, every

plugin. The how-do-I doc. | | MetaHarness Guide | 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. | |

Benchmarks | 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. | | Verification | Cryptographically

prove your installed bytes match the signed witness — ruflo verify. The trust-but-verify doc. | | **[Team Gateway

Checklist](docs/TEAM-GATEWAY-CHECKLIST.md)** | 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 ·

SOTA-PROGRESS.md · [raw matrix JSON:

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

linux

User Guide section index:

| Section | Topics | |---------|--------| | Quick Start | Installation, prerequisites, install profiles | | [Core

Features](docs/USERGUIDE.md#-core-features) | MCP tools, agents, memory, neural learning | | [Intelligence &

Learning](docs/USERGUIDE.md#-intelligence--learning) | Hooks, workers, SONA, model routing | | [Swarm &

Coordination](docs/USERGUIDE.md#-swarm--coordination) | Topologies, consensus, hive mind | | Security |

AIDefence, CVE remediation, validation | | Ecosystem | RuVector, agentic-flow, Flow Nexus | |

Configuration | Environment variables, config schema | | [Plugin

Marketplace](https://ruvnet.github.io/ruflo) | Browse and install plugins |

Support

| Resource | Link | |----------|------| | Documentation | User Guide | | Issues & Bugs | [GitHub

Issues](https://github.com/ruvnet/claude-flow/issues) | | Enterprise | ruv.io | | Community | [Agentics Foundation

Discord](https://discord.com/invite/dfxmpwkG2D) | | Powered by | Cognitum.one |

License

MIT - RuvNet