GitHub - ruvnet/ruflo: 🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build con

Ruflo

English · 简体中文

An agent meta-harness for Claude Code and Codex.

📖 RuFlo Explained — Build an AI Team That Plans, Remembers, Tests, and Improves A 14-chapter guide: from the basic idea to a first useful task, then memory, agent teams, plugins, cost and verification.

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.

📖 Background — where the name comes from

Claude Flow is now Ruflo — named by rUv , 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 agentic architecture, running a supercharged Rust-based AI engine, embeddings, memory, and plugin system.

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)

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.

🔌 All 35 plugins Core & Orchestration

Plugin What it does

ruflo-core Foundation — server, health checks, plugin discovery

ruflo-swarm Coordinate multiple agents as a team

ruflo-autopilot Let agents run autonomously in a loop

ruflo-loop-workers Schedule background tasks on a timer

ruflo-workflows Reusable multi-step task templates

ruflo-federation Agents on different machines collaborate securely

Memory & Knowledge

Plugin What it does

ruflo-agentdb Fast vector database for agent memory

ruflo-rag-memory Smart retrieval — hybrid search, graph hops, diversity ranking

ruflo-rvf Save and restore agent memory across sessions

ruflo-ruvector ruvector — GPU-accelerated search, Graph RAG, 103 tools

ruflo-knowledge-graph Build and traverse entity relationship maps

Intelligence & Learning

Plugin What it does

ruflo-intelligence Agents learn from past successes and get smarter

ruflo-graph-intelligence Sublinear graph reasoning — PageRank, delta updates, complexity-aware execution (ADR-123)

ruflo-daa Dynamic agent behavior and cognitive patterns

ruflo-ruvllm Run local LLMs (Ollama, etc.) with smart routing

ruflo-goals Break big goals into plans and track progress

Code Quality & Testing

Plugin What it does

ruflo-testgen Find missing tests and generate them automatically

ruflo-browser Automate browser testing with Playwright

ruflo-jujutsu Analyze git diffs, score risk, suggest reviewers

ruflo-docs Generate and maintain documentation automatically

Security & Compliance

Plugin What it does

ruflo-security-audit Scan for vulnerabilities and CVEs

ruflo-aidefence Block prompt injection, detect PII, safety scanning

Architecture & Methodology

Plugin What it does

ruflo-adr Track architecture decisions with a living record

ruflo-ddd Scaffold domain-driven design — contexts, aggregates, events

ruflo-sparc Guided 5-phase development methodology with quality gates

ruflo-metaharness Grade your agent setup, scan tool configs for security risks, and track changes over time ( guide )

ruflo-arena Competitive ruliology — pit agent strategies against each other in tournaments, hill-climb and co-evolve the winners (ADR-147/148)

DevOps & Observability

Plugin What it does

ruflo-migrations Manage database schema changes safely

ruflo-observability Structured logs, traces, and metrics in one place

ruflo-cost-tracker Track token usage, set budgets, get cost alerts

Extensibility

Plugin What it does

ruflo-agent Run agents — local WASM sandbox (rvagent) + Anthropic Claude Managed Agents (cloud)

ruflo-plugin-creator Scaffold, validate, and publish your own plugins

Domain-Specific

Plugin What it does

ruflo-iot-cognitum IoT device management — trust scoring, anomaly detection, fleets

ruflo-neural-trader neural-trader — AI trading with 4 agents, backtesting, 112+ tools

ruflo-market-data Ingest market data, vectorize OHLCV, detect patterns

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 .

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

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

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 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 · linux

User Guide section index:

Section Topics

Quick Start Installation, prerequisites, install profiles

Core Features MCP tools, agents, memory, neural learning

Intelligence & Learning Hooks, workers, SONA, model routing

Swarm & Coordination Topologies, consensus, hive mind

Security AIDefence, CVE remediation, validation

Ecosystem RuVector, agentic-flow, Flow Nexus

Configuration Environment variables, config schema

Plugin Marketplace Browse and install plugins

Support

Resource Link

Documentation User Guide

Issues & Bugs GitHub Issues

Enterprise ruv.io

Community Agentics Foundation Discord

Powered by Cognitum.one

License

MIT - RuvNet

— 本文由 AI 根据公开来源辅助整理，命令、版本与许可证请在使用前到原始页面复核。