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. Afterinit
, 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 |
/plugin marketplace add ruvnet/ruflo
/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-swarmruflo-autopilotruflo-loop-workersruflo-workflowsruflo-federation| Plugin | What it does | |---|---| ruflo-agentdb |
ruflo-rag-memoryruflo-rvfruflo-ruvector— GPU-accelerated search, Graph RAG, 103 toolsruvector
ruflo-knowledge-graph| Plugin | What it does | |---|---| ruflo-intelligence |
ruflo-graph-intelligenceruflo-daaruflo-ruvllm****ruflo-goals| Plugin | What it does | |---|---| ruflo-testgen |
ruflo-browserruflo-jujutsuruflo-docs| Plugin | What it does | |---|---| ruflo-security-audit |
ruflo-aidefence| Plugin | What it does | |---|---| ruflo-adr |
ruflo-dddruflo-sparcruflo-metaharnessguide)** 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+ toolsneural-trader
ruflo-market-data****macOS / Linux / WSL / Git-Bash:
curl -fsSL https://cdn.jsdelivr.net/gh/ruvnet/ruflo@main/scripts/install.sh | bash
All platforms (including native Windows PowerShell / cmd):
npx ruflo@latest init wizard
npm install -g ruflo@latest
💡
Windows users:thecurl ... | bash
form needs a POSIX shell (Git-Bash, WSL, MSYS). Thenpx ruflo@latest init wizard
line works natively in PowerShell and cmd. If you hit an'bash' is not recognized
error, use thenpx
line instead — both end up running the same init flow.
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 WorkersPlugin MarketplaceMulti-ProviderSecurityAgent FederationMetaHarnessruflo eject
turns a ruflo project into a standalone agent toolkit with its own name. Full guide.Web UI BetaRuFlo Research/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 | ||
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 callBring your own MCP serversMCP (n) pill in the chat input →Add Serverand 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 onlocalhost:3000
and it just works.Tools run in parallel* Step 1 — 2 tools completedbadge 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.iodemo is one option; running your own is fully supported.Zero install to try****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-033for the architecture and
issue #1689for 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 | |
Visual plan tree* exactlywhy an agent picked a path — no opaque chain-of-thought.**Adaptive replanningShared memory + SONAWired to MCP tools***Zero install to try**goal.ruv.io, describe a goal, watch it run. Source lives in— Vite + Supabase, self-hostable.v3/goal_ui/
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
.
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 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
npx claude-flow@latest federation init
npx claude-flow@latest federation join wss://team-b.example.com:8443
npx claude-flow@latest federation send --to team-b --type task-request \
--message "Analyze transaction patterns for account anomalies"
npx claude-flow@latest federation status
See issue #1669 for the complete architecture, trust model, and implementation roadmap.
/plugin install ruflo-federation@ruflo
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
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 ·
SOTA-PROGRESS.md
User Guide section index:
| Section | Topics |
|---|---|
Core FeaturesIntelligence & LearningSwarm & CoordinationSecurityEcosystemConfigurationPlugin Marketplace| Resource | Link | |---|---| | Documentation | |
GitHub Issuesruv.ioAgentics Foundation DiscordCognitum.oneMIT - RuvNet